Contents

Version 1.31

By Peter Kelly <ptrkelly@ozemail.com.au>

About AGI

About AGI Studio

What’s new in this version

Where to get more info on AGI

Learning about AGI

Data used by AGI

Logic help

Working with AGI Studio

Opening games

Creating new games

Viewing resources

Adding resources

Extracting resources

Deleting resources

Renumbering reources

Rebuilding the VOL files

Tools

View editor

Logic editor

Text editor

Object editor

WORDS.TOK editor

Picedit


About AGI

AGI (Adventure Game Interpreter) is the adventure game engine used by Sierra on-line to create some of their early games. With the release of King's Quest 1 in the early 80's, it introduced the gaming world to the concept of a 3D graphical adventure game, where the player could move a character around the screen, behind, in front of and over objects. Other commands could be typed in, just like a text adventure. A number of other games that used AGI were subsequently released, such as Space Quest 1 & 2, Police Quest 1 and Leisure Suit Larry 1 to name a few.

The graphics were rather blocky, using a 160x200 resolution, which I believe is because of the graphics mode used by the IBM PCjr, for which the interpreter was originally written. AGI used the internal speaker for sound on PCs, but on pretty much every other system (Mac, Amiga, Tandy, PCjr) it was capable of doing 3 voices.

A screenshot from King’s Quest 3

Since late 1996 a number of people around the world have been working together to figure out the data formats used by AGI, with the intention of being able to view and edit the data. It has taken a while, but we are now at the point where we can do this, and even create our own adventure games using the system.

Back to contents


About AGI Studio

AGI Studio is a program which allows you to view, create and edit AGI games.

Its features include:

•	Viewing of view and picture resources

•	Editing of view resources and the WORDS.TOK and OBJECT files

•	Compiling and decompiling of logic resources

•	Adding, deleting, extracting and renumbering of resources

•	Rebuilding of VOL files

AGI Studio is available from http://www.ozemail.com.au/~ptrkelly/agi

I started writing AGI Studio in September 1997. Its goal is to provide a friendly, easy to use interface to work with AGI games in a powerful, integrated environment.

Although pretty much all of the work for this program has been done by myself, I would like to thank the following people who have helped with various aspects:

Lance Ewing, for providing the version 3 decompression code used by the program and figuring out and documenting a lot of the file formats.

Jeremy Hayes, for providing interpreter version detecting code.

Alex Simkin and Serge Lapin for their work on a similar project a few years ago called AGDS, which among other things contained lots of information on logic programming.

Back to contents


What's new in this version
What’s new in this version

Version 1.31

•	Logic help

•	Resource size displayed in resource window

•	Printing available from logic editor and text editor

•	Fixed some small bugs with the view editor, resource renumbering and VOL file rebuilding

Version 1.3

New features

•	Logic editor

•	Text editor

•	Template game

•	Version 3 support

•	Settings dialog

Bugs fixed

•	View and picture resources not displaying properly in 256 colour mode due to palette problems

•	View editor not saving correctly in 256 colour mode

•	Major problems (including possible corruption) with VOL file rebuilding if the game was running

•	More crashes in view editor

•	WORDS.TOK editor not allowing spaces in words

Other stuff

•	Changed to MDI (Multiple Document Interface) for easier organisation of windows and a more professional look.

•	You can now create new games, instead of just being able to open existing ones.

•	Directory selection dialog now used when opening/creating games.

•	Splash screen at startup (this can be turned off in the settings dialog if you wish).

Back to contents


Where to get more info on AGI

For more info on AGI, visit my website at http://www.ozemail.com.au/~ptrkelly/agi

Detailed information on file formats, interpreter operation and logic programming is available in the AGI Specs documentation, available from http://www.ozemail.com.au/~ptrkelly/agi/specs

You can email me at ptrkelly@ozemail.com.au

Back to contents


Data used by AGI

Most data used by AGI is stored in resources. There are four types of resources, each storing a different type of data. Each AGI game can contain up to 256 resources of each type.

View resources - animations and sprites

Picture resources - background pictures

Sound resources - sound effects and music

Logic resources - scripts that determine what happens in the game

Other data:

The OBJECT file - list of inventory objects the player can get

The WORDS.TOK file - list of words accepted by the game

Files used by AGI

Back to contents


View resources

View resources contain some of the graphics for the game. Unlike the picture resources which are full-screen background images, view resources are smaller 'sprites' used in the game, such as animations. They are also stored as bitmaps, whereas pictures are stored in vector format.

Each view resource consists of one or more “loops”. Each loop in the resource consists of one or more “cels” (frames). Thus several animations can be stored in one view, or a view can just be used for a single image. The maximum number of loops supported by the interpreter is 255 (0-254) and the maximum number of cels in each is loop 255 (0-254).

Views have a number of useful features:

Transparency: Each cel has a transparent colour. When the view is shown on the screen, pixels of this colour will show to the background.

Mirroring: You can set one loop to be a “mirror” of another, which means that all the cels in that loop will be mirror images of the corresponding cels in the other loop. This is handy if you have drawn an animation of a character walking right, and also want to have an animation of it walking left - you only have to do half the work (and the view takes up less memory).

Description: This is used when a view is a picture of an inventory item. When the view is displayed using the show.obj command (i.e. when the player “examines” an object), the first cel of the first loop is displayed on screen along with the description.

AGI Studio supports up to 16 loops (0-15) and 32 cels in each loop (0-31).

You can edit Views with the view editor.

Back to data used by AGI


Picture resources

Picture resources are full-screen images, usually used for backgrounds. They are vector-based rather than bitmaps, which means they are drawn using drawing commands such as lines and brushes, rather than by plotting pixels.

Each picture has two images (screens) - the visual screen and the priority screen. The visual screen is what the player sees when playing the game. Views are placed on top of the pictures during the game and can be moved around the screen. The priority screen is what makes the game appear to be 3-dimensional. On the AGI screen, there are 12 priority bands in which objects can be placed. The priority given to different parts of the picture (i.e. the colour of the pixels on the priority screen) determines where in 3-dimensional space objects appear. For example, a tree placed right at the front of the screen would be given a priority of 15 (the highest priority). A wall which is far away in the background would be given a priority of 4 (the lowest priority). If an object with a priority of 12 is displayed on the screen, it would be behind the tree but in front of the wall. The priority of a view is usually determined by its y-position.

Colours 0, 1, 2 and 3 on the priority screen are used for “control lines” which determine where the ego (the object controlled by the player) can walk.

Back to data used by AGI


Sound resources

Sound resources contain all the sound effects and music used in a game. They consist of three musical voices plus one sound effect voice. The format is based on the sound capabilities of the IBM PC Junior, for which the interpreter was originally written. On standard PCs only the first music voice is played, because the only sound device available to the PC at the time was the internal speaker. There is no sound card support in the original PC version of the interpreter, but hopefully any new interpreters that are written will support this.

Other systems such as Macintosh and Amiga supported the other voices aswell.

Back to data used by AGI


Logic resources

Logic resources are the “guts” of an AGI game. They are scripts that contain all the commands necessary to control the view, picture and sound resources and to receive and act on input from the player, thus determining everything that happens in the game. Each room generally has its own logic which determines what happens in that room, and the game also has a few other logics to look after things like initialization and error handling.

Games are programmed in a special language specific to AGI and compiled into logic resources. The logic programming language is similar to standard programming languages like C, but a lot less powerful as it is designed for specific purpose. For more information on logic programming, click here

You can edit logics with the Logic editor.

Back to data used by AGI


The OBJECT file

The OBJECT file contains a list of inventory items (objects) that the player may possess during the game. Each item is numbered, and has a room number assigned to it. This room number is the room in which the object can be found.

It is not necessary to use these room numbers - it is up to the programmer to decide, but if they are used then the obj.in.room command can be used to find out if the object is in the current room when the player tries to get it.

Room 255 is the player’s inventory, so any inventory items the player is to have at the start of the game should have their room number set to this.

Note: Do not confuse inventory objects with screen objects. These are two completely different things. Inventory objects (or “inventory items”) are things that the player carries round with them during the game. Screen objects are views that are displayed on screen and represent things like characters and props. All the commands in the logic programming language that are called (something).obj refer to screen objects, except for show.obj and show.obj.v. Usually when the word “object” is used in the logic programming documentation it means screen object.

You can edit the OBJECT file with the Object editor

Back to data used by AGI


The WORDS.TOK file

The WORDS.TOK file contains a list of all the words that the game accepts. These words are sorted into groups of synonyms, and each group has a number. It is generally best to have several synonyms in each group, as this can reduce the “type ‘till you bleed” frustration that is typical in many parser-based games by making the input more flexible.

There are three groups that have special meaning:

Group 0: Words in this group are ignored. Examples of these sorts of words are “a”, “the”, “with”, “my” etc. When the player types in “poke the bush with the stick”, it is the same as typing in “poke bush stick”.

Group 1: This group should contain only one word, “anyword”. It can be used to respond to general statements such as “kill anyword”, e.g. if the player types “kill alligator”, “kill girl” or “kill plant” then the statement said(“kill”,”anyword”) will be TRUE.

Group 9999: This group should contain only one word, “rol”. rol means rest of line, e.g. if the player types “fight”, “fight beast” or “fight beast with sword” then the statement said(“fight”,”rol”) will be TRUE.

You can edit the WORDS.TOK file with the WORDS.TOK editor

Back to data used by AGI


Files used by AGI

Game files:

These are the files that contain the actual data for the game.

Vol files (VOL.*): These files contain the resources. They are stored one after the other in the file, with a small header at the start of each resource identifying its size.

Directory files (LOGDIR, PICDIR, VIEWDIR, SNDDIR): These store the locations of each resource in the VOL files.

OBJECT and WORDS.TOK: See data used by AGI section

In version 3, the VOL files have the game ID in front of them (e.g. KQ4VOL.0) and all the directory files are combined into one file (e.g. KQ4DIR)

If you want to know the format of these files, check out AGI Specs.

Interpreter files

These are the files used by Sierra’s original DOS interpreter. Other interpreters (there are two in progress at the time of writing) will use different files.

AGI: The interpreter itself

AGIDATA.OVL: Data used by the interpreter

Other .OVL files: Graphics drivers

SIERRA.COM: The loader file. Sometimes named after the game (e.g. SQ.COM). This loads the AGI file into memory, decrypts it, and then runs it.

Back to data used by AGI


Opening games

Before you can work on a game, you must open it. To do this, select ‘Open’ from the ‘File’ menu and then select directory containing the game you want to edit. This directory must contain a valid AGI version 2 or version 3 game.

Any changes you make to the game will be written to disk whenever you perform an operation such as adding or deleting a resource. In the built-in editors, the game is updated when you save or compile the resource.

Back to contents


Creating new games

To create a new game, select ‘New’ from the game menu. You can choose whether you want to create a completely “empty” game, or a game based on the template. Once you have done this, select the directory you want the game to be in (this directory must be empty).

The template game is a game with only one room, and all the menus, keys etc. already set up for you, along with names for most variables used and comments here and there. It is recommended you choose this option, as you can jump straight in and start programming your first room from here. For more information on the template game, see the readme.txt file in the template directory.

When you create a game, only the data files (and source code, if based on the template game) are placed in the directory you chose. You can not run the game yet because there is no interpreter there. You will need to copy the interpreter files from another game. The interpreter must be version 2.915 or higher (but not version 3). You can usually find out the version number of an interpreter when you enter debug mode in a game.

See the files used by AGI section to see what files you need to copy into the game directory. If you copy the files into the template directory, then whenever you create a new game from the template these will be copied also.

Note: If you are using a newly written AGI interpreter (although there are none available at the time of writing), then the version number will probably be different but new interpreters should support this format. The files you have to copy over will also be different.

You can get an interpreter from one of the AGI demos that are available (there are some on my site). I have recently written to Sierra asking permission to be able to distribute the interpreter, but I have not yet received a reply on whether or not it is ok. This is why I have not included an interpreter with the template game.

Back to contents


Viewing resources

To view a resource, just select it from the list in the resources window. You will see the resource in the preview window. At present this can only be done for view resources and picture resources.

Viewing view resources

When you click on a view resource, you will see the something like this:

To change loops or cels, just click on the apprioriate left/right buttons. There are also shortcut keys that you can use here:

Q	previous loop
W	next loop
A	previous cel
S	next cel

Viewing picture resources

When you click on a picture resource, you will see the something like this:

To view the visual or priority screen, select the appropriate radio button. You can also change screens by pressing ‘1’ for visual or ‘2’ for priority.

The picture viewer also allows you to copy the currently displayed screen to the clipboard or save it as a BMP file.

Back to contents


Adding resources

To add a resource, switch to the resources window and select ‘Add’ from the ‘Resource’ menu, or press INSERT. Select the file you want to add. Once a file is selected, you will be prompted for the resource type and number (the program will attempt to determine this from the name of the file).

In version 3 games, resources added or saved to the game are not compressed.

Back to contents


Extracting resources

To extract a resource, click on the resource you wish to extract and select ‘Extract’ from the ‘Resource’ menu, or press CTRL-E.

When the resource is extracted, it is saved to disk in its raw format (i.e. not converted to annother format such as BMP or midi). The 5 byte or 7 byte resource header used in the VOL files is not saved as this is not part of the resource. In version 3 games, the resource is uncompressed before saving to disk.

Back to contents


Deleting resources

To delete a resource, click on the resource you wish to delete and select ‘Delete’ from the ‘Resource’ menu or press DELETE. Note: Once you have deleted a resource, it is permanently deleted. There is no “undelete” feature.

Back to contents


Renumbering resources

To renumber a resource, select the resource you whish to renumber and select ‘Renumber’ from the ‘Resource’ menu or press CTRL-R.

Back to contents


Rebuilding the VOL files

This is the process of taking all the resources in a game and putting them in new VOL files. The time it takes depends on the size of the game, whether or not the resources are compressed, and the speed of your computer. Usually its between 1 and 20 seconds.

Note that the original AGI games were designed to be able to run from 360k floppy disks, where each VOL file went on a different disk. Because of this, each resource was carefully put on the right disk to minimise disk-swapping. When AGI Studio rebuilds the VOL files, it does not take any of this into account. This will not be a problem unless you then want to go and run the game off 360k floppies (the rebuilt files will may be too big to fit anyway).

In version 3 games, the resources are not compressed when the VOL files are rebuilt so the game will be a bit bigger if it was previously compressed.

To rebuild the VOL files, select ‘Rebuild VOL files’ from the ‘Resource’ menu.

Back to contents


View editor

The view editor supports all features of view resources. You can have up to 16 loops, 32 cels (in each loop), any width/height and a description. You can also copy and paste images from the clipboard.

For more information on view resources, click here.

To use the view editor, simply double-click on a view resource in the main window or select ‘View Editor’ from the ‘Tools’ menu or toolbar. You can have several view editor windows up at a time.

The view editor looks like this:

Components of the view editor window

Drawing area

This is pretty self explanatory. You can draw in either selected colour using the left or right mouse button.

Colour Palette

This allows you to select drawing colours. You can assign colours to the left or right mouse button by clicking that button on the appropriate colour.

Loop/cel change

The current loop and cel are displayed here. Click the left/right buttons to change loops/cels.

Width/height change

This is the width and height of the current cel. Note that the image is 2*width pixels wide on the screen as each AGI pixel is two normal pixels wide. To change the width or height, click on the appropriate buttons or type in a new value.

The maximum cel size is 160x168 (the size of the AGI playing screen).

Zoom in/out

You can zoom in or out of the view to a maximum of 10x. The default zoom is 2x.

Tool selection

This allows you to select the tool you want to use in the drawing area.

Shift cel

You can shift the cel up, down, left or right using these buttons. When you do this you will lose the part of the cel that goes off the drawing area.

Mirroring

To mirror a loop, just select the number of the loop you want to mirror. Note that when you do this, you lose the current loop and it is replaced with the mirror of the other loop. Always make sure that you change to the “target” loop before doing this.

When loops are mirrored, any change you make to either loop will be replicated in the other. When you select “No other loop”, the cels in both loops remain the same but you can now modify them independently.

Transparency

Clicking the “set” button will change the transparent colour of this cel to the colour that is assigned to the left mouse button.

Description

If you want a description, check the description check box and click the ‘Edit’ button to edit or change it. Note that lines are separated by “\n”. The description editor looks like this:

Shortcut Keys

These keys can be used with the view editor:

Q	previous loop
W	next loop
A	previous cel
S	next cel
Z	zoom out
X	zoom in
T	set transparent colour
D	select draw tool
F	select fill tool
I	shift cel up
K	shift cel down
J	shift cel left
L	shift cel right
CTRL-C	copy cel
CTRL-P	paste cel

A couple of notes

At present, the undo feature is not available for inserting/appending/ deleting/clearing loops or cels, mirroring/unmirroring loops or pasting cels. If you perform one of these actions, the undo buffer will be cleared. I hope to have undo available for all actions in future versions.

The reason pasting of cels from the clipboard is slower than it should be is that the program has to convert a 24-bit image to a 16-colour image by picking the closest EGA colour for every pixel. This is so you can import an image from another program that doesn't use exactly the same palette as AGI Studio. In future versions I hope to speed this up when pasting cels copied to the clipboard within the program.

Known bugs

When using the right mouse button for drawing, when you go off the edge of the

drawing area and come back again you will get a line from the point where you

left to the point where you re-entered.

Back to contents


Logic editor

The logic editor allows you to compile and decompile logic resources. To open an existing logic, double-click on it in the resources window, or to create a new one select ‘Logic editor’ from the ‘Tools’ menu or the toolbar (you will be prompted for the logic number when you save or compile it).

It is designed to be easier to use than its DOS counterparts in that you can save your source code, compile your logic, add it to the game and run the game all with the press of one key, eliminating the several steps and switching between applications previously required. It will also hilight any errors in the source code it encounters when compiling, so you can find them easily.

Previously, the syntax used for programming AGI logics has varied very slightly between compilers and has not been properly documented. Myself and other AGI developers have now decided on a proper syntax which will be supported by all logic compilers/decompilers. This syntax is documented in AGI specs. AGI Studio fully supports the syntax, although at the time of writing the logic compilers MATS and AGIC do not completely, although they will probably be fixed up soon.

Editing

When editing a logic, you edit the source code with a text editor (in this case the logic editor) and then compile it, as with most other programming languages. When you compile the logic in AGI Studio, it is automatically added to the game. The source code is saved in a text file in the “src” subdirectory of whatever game you are editing. The name of the file is “LogicX.txt” where X is the number of the logic. This file is saved whenever you compile the logic.

If you double-click on a logic in the resources window, the editor will be brought up. If the “LogicX.txt” file exists in the “src” directory, this will be loaded. Otherwise it will decompile the resource that is already in the game.

Compiling

To compile a logic, simply select compile from the file menu or press F9. Pressing F10 does the same thing except it runs the game after the logic has compiled successfully. Whenever you compile the logic, the source code and any open text files that are included with the #include command are saved.

This is basically all you need to know about AGI Studio’s logic editor. You will need to know how to program in the language though. This can best be done by looking at the code of existing games and reading the logic help included with AGI Studio.

Back to contents


Text editor

The text editor is included so you can edit text files without having to switch to another application such as notepad. This is especially handy when you are doing logic programming and you need to edit a file which is included in your logic using the #include command. It is also integrated with the logic editor - if a text file is used in a logic with the #include command and it contains an error, the compiler will bring up the text editor with the appropriate file and hilight the appropriate line so you can fix the error. Note that when you compile a logic, all open text files that are referred to by that logic are automatically saved.

Usage of the text editor is pretty self explanatory - it is very similar in operation to programs like notepad. You can open it from the ‘Tools’ menu or the toolbar.

Back to contents


Object editor

The Object editor allows you to create and edit the OBJECT file, which is used to store the names of inventory items available to the player during the game. For more information on the OBJECT file, click here.

To load the Object editor, select the option from the ‘Tools’ menu or the toolbar. When you do this, it will load the OBJECT file of the current game (if a game is open). You can then open a different file if you wish.

Most of the editing is pretty self-explanatory. There are a few things, however than need explanation:

All objects MUST have a name. The default name for an object that does not have a proper name is ‘?’. When you delete an object and it is not the last one in the list, it will be replaced with ‘?’. This is because moving the other objects up in the list would require re-compilation of all logics that refer to those objects, so it is better to leave the other object numbers as they are.

The OBJECT file must contain at least one object. A new OBJECT file will just contain the object ‘?’.

Encryption

In early versions of the interpreter (those before 2.411), the OBJECT file was not encrypted. The editor allows you to specify whether or not you want to encrypt the file. Just select ‘Encrypted file’ from the ‘Options’ menu. When opening a file, the editor automatically detects whether or not the file is encrypted.

Saving

Note: When saving a file, it does not necessarily have to be called OBJECT. It must have this name, however, for the interpreter to use it.

Back to contents


WORDS.TOK editor

The WORDS.TOK editor allows you to create and edit the WORDS.TOK file, which is used to store the words that the game accepts. For more information on the WORDS.TOK file, click here.

To load the WORDS.TOK editor, select the option from the ‘Tools’ menu or the toolbar. When you do this, it will load the WORDS.TOK file of the current game (if a game is open). You can then open a different file if you wish.

Editing

Down the left hand side of the window is the list of word groups. These are groups of synonyms. The words in each group are shown, separated by a |. To see more of each group, slide the middle separator to the right.

Clicking on one of these groups will bring up the contents of the word group in the right-hand pane. To edit a word, just click on it and it will appear in the edit box below. You can also add or delete words here.

You can add or delete word groups as well as changing their number. It does not really matter which word groups have which numbers, other than groups 0, 1 and 9999. You may, however want to structure your groups so that for example the first 20 or so are for general game functions, the next 20 or so are the names of inventory objects and the other words are put after that. It’s up to you how you do this.

Your word group structure may become important when you want to merge this file with others.

Merging

The WORDS.TOK editor has the ability to merge files. This means combining two WORDS.TOK files by taking words from each file. To merge another file into the current one, select ‘Merge’ from the ‘File’ menu.

When merging a file, if a word exists in the merge file that is already in the current file (and in a different group), you will be asked if you wish to replace it or not. When merging files you should be careful about which words you replace as some commands may no longer be recognised by the game. You may need to recompile some or all logics after merging so that they refer to the right word groups in the right places.

You shouldn’t need to merge files that often, but when you do it is worth comparing the two files closely. If you’re not careful, merging can alter the way commands are understood. For example, “glasses” may be synonymous with “spectacles” at first, but depending on what is in the merge file you might end up with “glasses” being synonymous with “beer mugs”.

Note that the merge file (the one you are merging into the current file) is not modified in any way. The changes to the current file made by merging are only saved to disk when you save the file.

Finding words

A search feature has been added to help locate words without having to look through the word group. You can search for all or part of a word, and the find dialog will step through all the occurrences of the text.

Saving

Note: When saving a file, it does not necessarily have to be called WORDS.TOK. It must have this name, however, for the interpreter to use it.

If you try to save a file containing empty word groups, these will not be saved as the file format does not allow for empty groups. The program will not let you save a file if it does not have any groups. The only reason empty groups are allowed is because they can make editing a bit more convenient.

A note about valid words

To my knowledge, the only characters in words recognised by the interpreter are letters, numbers and spaces. The letters are all lower case, as the parser input is not case sensitive. If you enter a word with any characters other than these, they will be automatically removed. Uppercsae letters are converted to lower case.

Back to contents


Picedit

Picedit is not actually part of AGI Studio. It is a program written by Lance Ewing <be@ihug.co.nz> that allows you to edit picture resources. It is not included with AGI Studio, but if you have a copy and you place picedit.exe in the same directory as AGI Studio, you can run it from the ‘Tools’ menu or the toolbar.

Back to contents


AGI Logic help

Getting started

General topics

Logic syntax

Types

Objects

Special variable

Special flags

Command reference

Commands by name

Commands by category


Commands by name

Test commands

equaln

equalv

lessn

lessv

greatern

greaterv

isset

issetv

has

obj.in.room

posn

controller

have.key

said

compare.strings

obj.in.box

center.posn

right.posn

Action commands

accept.input

add.to.pic.v

add.to.pic

addn

addv

animate.obj

assignn

assignv

block

call.v

call

cancel.line

clear.lines

clear.text.rect

close.dialogue

close.window

configure.screen

current.cel

current.loop

current.view

cycle.time

decrement

disable.item

discard.pic

discard.view.v

discard.view

display.v

display

distance

div.n

div.v

draw.pic

draw

drop

echo.line

enable.item

end.of.loop

erase

fix.loop

follow.ego

force.update

get.dir

get.num

get.posn

get.priority

get.room.v

get.string

get.v

get

graphics

ignore.blocks

ignore.horizon

ignore.objs

increment

init.disk

init.joy

last.cel

lindirectn

lindirectv

load.logics.v

load.logics

load.pic

load.sound

load.view.v

load.view

log

menu.input

move.obj.v

move.obj

mul.n

mul.v

new.room.v

new.room

normal.cycle

normal.motion

number.of.loops

obj.status.v

object.on.anything

object.on.land

object.on.water

observe.blocks

observe.horizon

observe.objs

open.dialogue

overlay.pic

parse

pause

player.control

position.v

position

prevent.input

print.at.v

print.at

print.v

print

program.control

put.v

put

quit

random

release.loop

release.priority

reposition.to.v

reposition.to

reposition

reset.scan.start

reset.v

reset

restart.game

restore.game

return

reverse.cycle

reverse.loop

rindirect

save.game

script.size

set.cel.v

set.cel

set.cursor.char

set.dir

set.game.id

set.horizon

set.key

set.loop.v

set.loop

set.menu.item

set.menu

set.priority.v

set.priority

set.scan.start

set.string

set.text.attribute

set.upper.left

set.view.v

set.view

set.v

set

shake.screen

show.mem

show.obj.v

show.obj

show.pic

show.pri.screen

sound

start.cycling

start.motion

start.update

status.line.off

status.line.on

status

step.size

step.time

stop.cycling

stop.motion

stop.sound

stop.update

submit.menu

subn

subv

text.screen

toggle.monitor

toggle.v

toggle

trace.info

trace.on

unanimate.all

unblock

unknown170

unknown171

unknown172

unknown173

unknown174

unknown175

unknown176

unknown177

unknown178

unknown179

unknown180

unknown181

version

wander

word.to.string


Commands by category

Test commands

Mathematical commands

Flag commads

Control flow commands

Picture commands

Debugging commands

Object/view commands

Inventory item commands

Sound commands

Display commands

Menu/Key commands

System commands

String commands

Unknown commands


Test commands

equaln

equalv

lessn

lessv

greatern

greaterv

isset

issetv

has

obj.in.room

posn

controller

have.key

said

compare.strings

obj.in.box

center.posn

right.posn


Mathematical commands

addn

addv

assignn

assignv

decrement

div.n

div.v

get.num

increment

lindirectn

lindirectv

mul.n

mul.v

random

rindirect

subn

subv

Test commands

equaln

equalv

lessn

lessv

greatern

greaterv


Flag commads

reset.v

reset

set.v

set

toggle.v

toggle

Test commands

isset

issetv


Control flow commands

call.v

call

load.logics.v

load.logics

new.room.v

new.room

reset.scan.start

return

set.scan.start


Picture commands

discard.pic

draw.pic

load.pic

overlay.pic

show.pic


Debugging commands

log

obj.status.v

show.mem

show.pri.screen

trace.info

trace.on

version


Object/view commands

For more information on objects, click here.

add.to.pic.v

add.to.pic

animate.obj

block

current.cel

current.loop

current.view

cycle.time

discard.view.v

discard.view

distance

draw

end.of.loop

erase

fix.loop

follow.ego

force.update

get.dir

get.posn

get.priority

ignore.blocks

ignore.horizon

ignore.objs

last.cel

load.view.v

load.view

move.obj.v

move.obj

normal.cycle

normal.motion

number.of.loops

object.on.anything

object.on.land

object.on.water

observe.blocks

observe.horizon

observe.objs

position.v

position

release.loop

release.priority

reposition.to.v

reposition.to

reposition

reverse.cycle

reverse.loop

set.cel.v

set.cel

set.dir

set.horizon

set.loop.v

set.loop

set.priority.v

set.priority

set.upper.left

set.view.v

set.view

start.cycling

start.motion

start.update

step.size

step.time

stop.cycling

stop.motion

stop.update

unanimate.all

unblock

wander

Test commands

posn

obj.in.box

center.posn

right.posn


Inventory item commands

drop

get.room.v

get.v

get

put.v

put

show.obj.v

show.obj

status

Test commands

has

obj.in.room


Sound commands

load.sound

sound

stop.sound


Display commands

For more information on displaying text, click here.

clear.lines

clear.text.rect

close.dialogue

close.window

configure.screen

display.v

display

graphics

open.dialogue

print.at.v

print.at

print.v

print

set.cursor.char

set.text.attribute

shake.screen

status.line.off

status.line.on

text.screen


Menu/Key commands

For information on setting up menu items and keys, click here.

disable.item

enable.item

menu.input

set.key

set.menu.item

set.menu

submit.menu

Test commands

controller


System commands

accept.input

cancel.line

echo.line

init.disk

init.joy

pause

player.control

prevent.input

program.control

quit

restart.game

restore.game

save.game

script.size

set.game.id

toggle.monitor


String commands

get.string

parse

set.string

word.to.string

Test commands

compare.strings


Unknown commands

unknown170

unknown171

unknown172

unknown173

unknown174

unknown175

unknown176

unknown177

unknown178

unknown179

unknown180

unknown181


return

Category

Control flow commands

Syntax

return();

Description

Ends execution of the current logic and returns to the logic that called it (or in the case of logic 0, goes on to the next interpreter cycle).

This command is required at the end of every logic.

See also


increment

Category

Mathematical commands

Syntax

increment(vA);

vA++;

Description

If the value of vA is less than 255, then it is increased by 1.

See also

decrement


decrement

Category

Mathematical commands

Syntax

decrement(vA);

vA--;

Description

If the value of vA is greater than 0, then it is decreased by 1.

See also

increment


assignn

Category

Mathematical commands

Syntax

assignn(vA,B);

vA = B;

Description

The value of vA is set to B.

See also

assignv


assignv

Category

Mathematical commands

Syntax

assignv(vA,vB);

vA = vB;

Description

The value of vA is set to the value of vB.

See also

assignn


addn

Category

Mathematical commands

Syntax

addn(vA,B);

vA += B;

vA = vA + B;

Description

B is added to vA. Since a var can only be from 0-255, if the result is greater than 255, then the value “wraps around”, e.g. 250 + 10 would give 4.

See also

addv


addv

Category

Mathematical commands

Syntax

addv(vA,vB);

vA += vB;

vA = vA + vB;

Description

vB is added to vA. Since a var can only be from 0-255, if the result is greater than 255, then the value “wraps around”, e.g. 250 + 10 would give 4.

See also

addn


subn

Category

Mathematical commands

Syntax

subn(vA,B);

vA -= B;

vA = vA - B;

Description

B is subtracted from vA. Since a var can only be from 0-255, if the result is less than 0, then the value “wraps around”, e.g. 10 - 12 would give 254.

See also

subv


subv

Category

Mathematical commands

Syntax

subv(vA,vB);

vA -= vB;

vA = vA - vB;

Description

vB is subtracted from vA. Since a var can only be from 0-255, if the result is less than 0, then the value “wraps around”, e.g. 10 - 12 would give 254.

See also

subn


lindirectv

Category

Mathematical commands

Syntax

lindirectn(vA,vB);

*vA = vB;

Description

The value of vC (where C is the value of vA) is set to vB.

See also

lindirectn

rindirect


rindirect

Category

Mathematical commands

Syntax

rindirect(vA,vB);

vA = *vB;

Description

The value of vA is set to vC (where C is the value of vB).

See also

lindirectv

lindirectn


lindirectn

Category

Mathematical commands

Syntax

lindirectn(vA,B);

*vA = B;

Description

The value of vC (where C is the value of vA) is set to B.

See also

lindirectv

rindirect


set

Category

Flag commads

Syntax

set(fA);

Description

Flag fA is set.

See also

set.v


reset

Category

Flag commads

Syntax

reset(fA);

Description

Flag fA is reset.

See also

reset.v


toggle

Category

Flag commads

Syntax

toggle(fA);

Description

If flag fA is set, then it is reset. Otherwise it is set.

See also

toggle.v


set.v

Category

Flag commads

Syntax

set.v(vA);

Description

Flag fB (where B is the value of vA) is set.

See also

set


reset.v

Category

Flag commads

Syntax

reset.v(vA);

Description

Flag fB (where B is the value of vA) is reset.

See also

reset


toggle.v

Category

Flag commads

Syntax

toggle.v(vA);

Description

If flag fB (where B is the value of vA) is set, then it is reset. Otherwise it is set.

See also

toggle


new.room

Category

Control flow commands

Syntax

new.room(ROOMNO);

Description

Switches to a new room, ROOMNO.

The following things automatically happen when this command is used:

•	All objects are unanimated

•	All resources except logic 0 are discarded

•	player.control command is executed

•	unblock command is executed

•	horizon is set to 36

•	v1 (prev_room_no) is set to the value of v0 (room_no)

•	v0 (room_no) is assigned to the new room number

•	v16 (ego_view_no) is set to the view number assigned to ego

•	The logic for the new room is loaded (logic ROOMNO)

•	If ego was touching an edge of the screen, it is placed on the opposite side

•	Flag 5 (new_room) is set (this is reset after the first cycle in the new room)

•	Execution jumps to the start of logic 0

See also

new.room.v

player.control

unblock

set.horizon

Special variables

Special flags


new.room.v

Category

Control flow commands

Syntax

new.room(vROOMNO);

Description

Switches to a new room, vROOMNO.

The following things automatically happen when this command is used:

•	All objects are unanimated

•	All resources except logic 0 are discarded

•	player.control command is executed

•	unblock command is executed

•	horizon is set to 36

•	v1 (prev_room_no) is set to the value of v0 (room_no)

•	v0 (room_no) is assigned to the new room number

•	v16 (ego_view_no) is set to the view number assigned to ego

•	The logic for the new room is loaded (logic vROOMNO)

•	If ego was touching an edge of the screen, it is placed on the opposite side

•	Flag 5 (new_room) is set (this is reset after the first cycle in the new room)

Execution jumps to the start of logic 0

See also

new.room

player.control

unblock

set.horizon

Special variables

Special flags


load.logics

Category

Control flow commands

Syntax

load.logics(A);

Description

Loads logic A is into memory. You should do this if you are going to call it a lot, to save the inrepter having to load it and unload it every time it calls it.

See also

load.logics.v

call


load.logics.v

Category

Control flow commands

Syntax

load.logics.v(vA);

Description

Loads logic vA is into memory. You should do this if you are going to call it a lot, to save the inrepter having to load it and unload it every time it calls it.

See also

load.logics

call


call

Category

Control flow commands

Syntax

call(A);

Description

Logic A is executed once. If it is not already loaded into memory, it is loaded before being called and then unloaded again afterwards.

See also

call.v

load.logics


call.v

Category

Control flow commands

Syntax

call.v(vA);

Description

Logic vA is executed once. If it is not already loaded into memory, it is loaded before being called and then unloaded again afterwards.

See also

call

load.logics


load.pic

Category

Picture commands

Syntax

load.pic(vA);

Description

Picture resource vA is loaded into memory.

See also

discard.pic

draw.pic

overlay.pic

Drawing pictures


draw.pic

Category

Picture commands

Syntax

draw.pic(vA);

Description

Picture vA is drawn. Only the visual and priority screens in memory updated - not the actual screen itself. To update the screen, use the show.pic command. Make sure the picture is loaded into memory before drawing it.

See also

overlay.pic

load.pic

Drawing pictures


show.pic

Category

Picture commands

Syntax

show.pic();

Description

The visual screen held in memory is updated on the actual screen.

See also

Drawing pictures


discard.pic

Category

Picture commands

Syntax

discard.pic(vA);

Description

Picture resource vA is discarded from memory. If the picture is not already loaded, the interpreter generates an error.

See also

load.pic

Drawing pictures


overlay.pic

Category

Picture commands

Syntax

overlay.pic(vA);

Description

overlay.pic does the same thing as draw.pic, except that the visual and priority screens are not cleared. This means that picture vA is drawn on top of the existing picture. Note that because fills only work on white surfaces, fills in picture vA which are not on a white part of the existing picture won’t work. It’s generally best not to use and fills in pictures that you intend to overlay.

Remember to use show.pic to update the screen once the picture has been overlayed.

Make sure the picture is loaded into memory before overlaying it.

See also

draw.pic

load.pic

Drawing pictures


show.pri.screen

Category

Debugging commands

Syntax

show.pri.screen();

Description

Displays the priority screen.

See also

Priorities


load.view

Category

Object/view commands

Syntax

load.view(VIEWNUM);

Description

View VIEWNUM is loaded into memory. This is required before the view is assigned to any objects or used anywhere. It is not needed, however, for the show.obj command.

See also

load.view.v

discard.view

discard.view.v

set.view

set.view.v


load.view.v

Category

Object/view commands

Syntax

load.view(vVIEWNUM);

Description

View vVIEWNUM is loaded into memory. This is required before the view is assigned to any objects or used anywhere. It is not needed, however, for the show.obj command.

See also

load.view

discard.view

discard.view.v

set.view

set.view.v


discard.view

Category

Object/view commands

Syntax

discard.view(VIEWNUM);

Description

View VIEWNUM is discarded from memory. If the view is not already loaded, the interpreter generates an error. Make sure you do not have the view assigned to any objects before you discard it.

See also

discard.view.v

load.view

load.view.v


animate.obj

Category

Object/view commands

Syntax

animate.obj(oA);

Description

This tells the interpreter to activate oA. You must do this before doing anything with the object.

See also

unanimate.all

Initializing objects


unanimate.all

Category

Object/view commands

Syntax

unanimate.all();

Description

This deactivates all screen objects.

See also

animate.obj


draw

Category

Object/view commands

Syntax

draw(oA);

Description

Object oA is drawn on screen.

See also

erase


erase

Category

Object/view commands

Syntax

erase(oA);

Description

Object oA is erased from the screen.

See also

draw


position

Category

Object/view commands

Syntax

position(oA,X,Y);

Description

The position on the screen of object oA is changed to X,Y. The position command should only be used if the object is not on screen (either it has not been drawn yet, or it has been erased). To change the position of an object that is already on screen, use the resposition.to command.

See also

position.v

reposition.to

reposition.to.v

reposition

Positioning objects


position.v

Category

Object/view commands

Syntax

position.v(oA,vX,vY);

Description

The position on the screen of object oA is changed to vX,vY. The position command should only be used if the object is not on screen (either it has not been drawn yet, or it has been erased). To change the position of an object that is already on screen, use the resposition.to.v command.

See also

position

reposition.to

reposition.to.v

reposition

Positioning objects


get.posn

Category

Object/view commands

Syntax

get.posn(oA,vX,vY);

Description

vX and vY are set to the X and Y co-ordinates of object oA.

See also

Positioning objects


reposition

Category

Object/view commands

Syntax

reposition(oA,vDX,vDY);

Description

Object oA is repositioned relative to it’s current co-ordinates. It’s new co-ordinates are X+vDX,Y+vDY where X,Y is it’s current position. If vDX or vDY are greater than 127, they are treated as a negative number (vDX-256 or vDY-256).

For example:

v254 = 5;

v255 = 252;

reposition(o1,v254,v255)

would reposition object 1 to X+5,Y-4.

See also

reposition.to

reposition.to.v

position

position.v

Positioning objects


set.view

Category

Object/view commands

Syntax

set.view(oA,B);

Description

View B is assigned to object oA. The view must be loaded in order to do this. If you wish, you can have one view assigned to several objects.

See also

set.view.v

load.view

load.view.v

current.view


set.view.v

Category

Object/view commands

Syntax

set.view.v(oA,vB);

Description

View vB is assigned to object oA. The view must be loaded in order to do this. If you wish, you can have one view assigned to several objects.

See also

set.view

load.view

load.view.v

current.view


set.loop

Category

Object/view commands

Syntax

set.loop(oA,B);

Description

The current loop of object oA is set to B. If an invalid loop number is given, the interpreter generates an error. If the current cel of the object is greater than the last cel in loop B, then the current cel is set to 0.

See also

set.loop.v

current.loop

number.of.loops

set.cel

set.cel.v

Cycling objects


set.loop.v

Category

Object/view commands

Syntax

set.loop.v(oA,vB);

Description

The current loop of object oA is set to vB. If an invalid loop number is given, the interpreter generates an error. If the current cel of the object is greater than the last cel in loop vB, then the current cel is set to 0.

See also

set.loop

current.loop

number.of.loops

set.cel

set.cel.v

Cycling objects


fix.loop

Category

Object/view commands

Syntax

fix.loop(oA);

Description

This stops the interpreter from choosing the loop number for object oA based on it’s direction. You can turn this back on again using the release.loop command.

See also

release.loop

Cycling objects


release.loop

Category

Object/view commands

Syntax

release.loop(oA);

Description

This enables the interpreter to choose the loop number of an object based on it’s direction.

See also

fix.loop

Cycling objects


set.cel

Category

Object/view commands

Syntax

set.cel(oA,B);

Description

The current cel of object oA is set to B. If an invalid cel number is given, the interpreter will generates an error (the number of the last cel in a loop can be determined using the last.cel command).

See also

set.cel.v

current.cel

last.cel

set.loop

set.loop.v

Cycling objects


set.cel.v

Category

Object/view commands

Syntax

set.cel.v(oA,vB);

Description

The current cel of object oA is set to vB. If an invalid cel number is given, the interpreter will generates an error (the number of the last cel in a loop can be determined using the last.cel command).

See also

set.cel

current.cel

last.cel

set.loop

set.loop.v

Cycling objects


last.cel

Category

Object/view commands

Syntax

last.cel(oA,vB);

Description

vB is set to the number of the last cel of the current loop of object oA.

See also

current.cel

set.cel

set.cel.v

number.of.loops


current.cel

Category

Object/view commands

Syntax

current.cel(oA,vB);

Description

vB is set to the number of the current cel of object oA.

See also

last.cel

set.cel

set.cel.v

current.loop


current.loop

Category

Object/view commands

Syntax

current.loop(oA,vB);

Description

vB is set to the number of the current loop of object oA.

See also

number.of.loops

set.loop

set.loop.v

current.cel


current.view

Category

Object/view commands

Syntax

current.view(oA,vB);

Description

vB is set to the number of the view currently assigned to object oA.

See also

set.view

set.view.v


number.of.loops

Category

Object/view commands

Syntax

number.of.loops(oA,vB);

Description

vB is set to the number of loops in the view currently assigned to object oA.

See also

set.loop

set.loop.v

current.loop

last.cel


set.priority

Category

Object/view commands

Syntax

set.priority(oA,PRI);

Description

Object oA’s priority is set to PRI. The object keeps this priority wherever it goes on the screen.

To change it back so the priority is dependent on the object’s position, use the release.priority command.

Note: If the object’s priority is 15, it ignores all control lines and blocks, and thus can move anywhere on the screen below the horizon. If the object is ego (object 0), then flags 0 and 3 are no longer set according to whether ego is on a control line of colour 3 or 2. After this, if the object’s priority is released or set to something lower than 15, it returns to it’s normal behaviour.

See also

set.priority.v

release.priority

Priorities


set.priority.v

Category

Object/view commands

Syntax

set.priority.v(oA,vPRI);

Description

Object oA’s priority is set to vPRI. The object keeps this priority wherever it goes on the screen.

To change it back so the priority is dependent on the object’s position, use the release.priority command.

Note: If the object’s priority is 15, it ignores all control lines and blocks, and thus can move anywhere on the screen below the horizon. If the object is ego (object 0), then flags 0 and 3 are no longer set according to whether ego is on a control line of colour 3 or 2. After this, if the object’s priority is released or set to something lower than 15, it returns to it’s normal behaviour.

See also

set.priority

release.priority

Priorities


release.priority

Category

Object/view commands

Syntax

release.priority(oA);

Description

If object oA’s priority was previously set, it is “released” which means that the priority now depends on the position of the object.

See also

set.priority

set.priority.v

Priorities


get.priority

Category

Object/view commands

Syntax

get.priority(oA,vPRI);

Description

vPRI is set to the priority of object oA.

See also

Priorities


stop.update

Category

Object/view commands

Syntax

stop.update(oA);

Description

This tells the interpreter not to update object oA at the start of every cycle. The object remains on screen, unchanged.

See also

start.update

force.update


start.update

Category

Object/view commands

Syntax

start.update(oA);

Description

This tells the interpreter to update object oA at the start of every cycle.

See also

stop.update

force.update


force.update

Category

Object/view commands

Syntax

force.update(oA);

Description

Object oA is redrawn immediately, without waiting till the start of the next interpreter cycle.

See also

start.update

stop.update

Cycling objects


ignore.horizon

Category

Object/view commands

Syntax

ignore.horizon(oA);

Description

Object oA is allowed to go above the horizon.

See also

observe.horizon

set.horizon

Controlling obstacles


observe.horizon

Category

Object/view commands

Syntax

observe.horizon(oA);

Description

Object oA is not allowed to go above the horizon.

See also

ignore.horizon

set.horizon

Controlling obstacles


set.horizon

Category

Object/view commands

Syntax

set.horizon(Y);

Description

The horizon’s vertical position is set to Y. The horizon is an invisible horizontal line, usually near the top of the screen. The default value for the horizon (when the new.room command is used) is 36. Objects are not allowed above the horizon, unless you use the ignore.horizon command.

See also

ignore.horizon

observe.horizon

Controlling obstacles


object.on.water

Category

Object/view commands

Syntax

object.on.water(oA);

Description

Object oA is only allowed to be on water (pixels with a priority of 3).

See also

object.on.land

object.on.anything

Controlling obstacles


object.on.land

Category

Object/view commands

Syntax

object.on.land(oA);

Description

Object oA is not allowed to be on water (pixels with a priority of 3).

See also

object.on.water

object.on.anything

Controlling obstacles


object.on.anything

Category

Object/view commands

Syntax

object.on.anything(oA);

Description

Object oA is allowed to be on land or water.

See also

object.on.water

object.on.land

Controlling obstacles


ignore.objs

Category

Object/view commands

Syntax

ignore.objs(oA);

Description

Object oA is allowed to move through other objects, i.e. it’s baseline is allowed to touch another object’s baseline.

If oA stops because it runs into another object, it will keep going once that object moves out of the way (provided it is not stopped or it’s direction changed before then).

See also

observe.objs

Controlling obstacles


observe.objs

Category

Object/view commands

Syntax

observe.objs(oA);

Description

Object oA is prohibited from moving through other objects, i.e. it’s baseline is not allowed to touch another object’s baseline.

See also

ignore.objs

Controlling obstacles


distance

Category

Object/view commands

Syntax

distance(oA,oB,vD);

Description

vD is set to the distance between objects oA and oB. The formula used for calculating the distance is abs(x1-x2) + abs(y1-y2) where x1,y1 and x2,y2 are the co-ordinates of the center of the baselines of oA and oB.

If one or more of the objects is not on screen, the distance is 255.

See also


stop.cycling

Category

Object/view commands

Syntax

stop.cycling(oA);

Description

This tells the interpreter to stop cycling object oA. To turn cycling back on, use the start.cycling command.

See also

start.cycling

normal.cycle

reverse.cycle

Cycling objects


start.cycling

Category

Object/view commands

Syntax

start.cycling(oA);

Description

This tells the interpreter to start cycling object oA. If the object was previously cycling in reverse order before it was stopped, then it will continue to cycle in reverse order. Otherwise, it will cycle in normal order. To turn cycling off, use the stop.cycling command.

See also

stop.cycling

normal.cycle

reverse.cycle

Cycling objects


normal.cycle

Category

Object/view commands

Syntax

normal.cycle(oA);

Description

This tells the interpeter to cycle object oA in normal order, so the cels are shown from first to last. To turn cycling off, use the stop.cycling command.

See also

reverse.cycle

stop.cycling

start.cycling

Cycling objects


end.of.loop

Category

Object/view commands

Syntax

end.of.loop(oA,fB);

Description

Object oA is cycled in normal order until the last cel in the loop is reached. Flag fB is reset when the command is issued, and when the last cel is displayed fB is set.

See also

reverse.loop

Cycling objects


reverse.cycle

Category

Object/view commands

Syntax

reverse.cycle(oA);

Description

This tells the interpeter to cycle object oA in reverse order, so the cels are shown from last to first. To turn cycling off, use the stop.cycling command.

See also

normal.cycle

stop.cycling

start.cycling

Cycling objects


reverse.loop

Category

Object/view commands

Syntax

end.of.loop(oA,fB);

Description

Object oA is cycled in reverse order until the first cel in the loop is reached. Flag fB is reset when the command is issued, and when the first cel is displayed fB is set.

See also

end.of.loop

Cycling objects


cycle.time

Category

Object/view commands

Syntax

cycle.time(oA,vB);

Description

The delay (in interpreter cycles) between cel changes of object oA (when it is cycling) is set to vB. If vB is equal to 0, the cels do not change (even when the object is cycling). Note that an object’s cycle time is separate to it’s step time.

See also

step.time

Cycling objects


stop.motion

Category

Object/view commands

Syntax

stop.motion(oA);

Description

Object oA stops moving. If the object is ego (object 0), the program.control command is issued by the interpreter.

See also

start.motion

program.control

Moving objects


start.motion

Category

Object/view commands

Syntax

start.motion(oA);

Description

I am not quite sure what this command does. The name implies that object oA starts to move, but this does not seem to work (instead you have to use set.dir to set the direction of the object to something other than 0).

If oA is ego (object 0), the player.control command is issued by the interpreter.

See also

stop.motion

set.dir

player.control

Moving objects


step.size

Category

Object/view commands

Syntax

step.size(oA,vB);

Description

The step size of oA (the number of pixels it moves each step) is set to vB.

See also

step.time

move.obj

move.obj.v

follow.ego

Moving objects


step.time

Category

Object/view commands

Syntax

step.time(oA,vB);

Description

The delay (in interpreter cycles) between steps (movements) of object oA is set to vB. For example, if the step time is set to 2, the object will only move every second cycle. Note that an object’s step time is independent from it’s cycle time.

See also

step.size

cycle.time

Moving objects


move.obj

Category

Object/view commands

Syntax

move.obj(oA,X,Y,STEPSIZE,fDONEFLAG);

Description

Object oA moves from it’s current location to X,Y by STEPSIZE pixels every step. fDONEFLAG is reset when the command is issued, and set when the object reaches it’s destination. If STEPSIZE is 0, the current step size of object oA is used. If object oA is ego (object 0), the interpreter executes the program.control command.

Warning: If your program is relying on the flag fDONEFLAG to be set before continuing with something, such as going to the next part of a cutscene, make sure that the object will always be able to reach it’s destination. It is possible that it could get caught behind a barrier or something, and not be able to get where it needs to go, in which case the game might sit there forever doing nothing. This is more of a problem when the object being moved is ego - it might work fine from where you test it, but it may be possible for the player to move ego into such a position where they will get “stuck” when being moved.

See also

move.obj.v

step.size

normal.motion

Moving objects


move.obj.v

Category

Object/view commands

Syntax

move.obj.v(oA,vX,vY,STEPSIZE,fDONEFLAG);

Description

Object oA moves from it’s current location to vX,vY by STEPSIZE pixels every step. fDONEFLAG is reset when the command is issued, and set when the object reaches it’s destination. If STEPSIZE is 0, the current step size of object oA is used. If object oA is ego (object 0), the interpreter executes the program.control command.

Warning: If your program is relying on the flag fDONEFLAG to be set before continuing with something, such as going to the next part of a cutscene, make sure that the object will always be able to reach it’s destination. It is possible that it could get caught behind a barrier or something, and not be able to get where it needs to go, in which case the game might sit there forever doing nothing. This is more of a problem when the object being moved is ego - it might work fine from where you test it, but it may be possible for the player to move ego into such a position where they will get “stuck” when being moved.

See also

move.obj

step.size

Moving objects


follow.ego

Category

Object/view commands

Syntax

follow.ego(oA,STEPSIZE,fDONEFLAG);

Description

Object oA moves towards ego (object 0) by STEPSIZE pixels every step. When the object is within STEPSIZE pixels of ego, it stops moving and flag fDONEFLAG is set. If STEPSIZE is 0, the current step size of object oA is used.

See also

step.size

Moving objects


wander

Category

Object/view commands

Syntax

wander(oA);

Description

Object oA wanders randomly around the screen.

See also

Moving objects


normal.motion

Category

Object/view commands

Syntax

normal.motion(oA);

Description

Object oA moves normally. That is, if the object was wandering or following ego, or it was moving to a location specified by a move.obj command, it continues in the direction it was travelling, until it is told to stop, move in another direction or runs into an obstacle.

See also

move.obj

Moving objects


set.dir

Category

Object/view commands

Syntax

set.dir(oA,vDIR);

Description

The direction of object oA is changed ot vDIR. vDIR must be between 0 and 8:

You can not set the direction of ego (object 0). Instead, change the value of v6 to the direction you want.

To find out what direction an object is currently travelling in, use the get.dir command.

See also

get.dir

start.motion

Moving objects


get.dir

Category

Object/view commands

Syntax

get.dir(oA,vDIR);

Description

vDIR is set to the direction object oA is currently travelling in. The value will be between 0 and 8:

See also

set.dir

Moving objects


ignore.blocks

Category

Object/view commands

Syntax

ignore.blocks(oA);

Description

Object oA is allowed to cross over conditional barriers (pixels set to colour 1 on the priority screen) and borders of blocks set up with the block command.

See also

observe.blocks

block

Controlling obstacles


observe.blocks

Category

Object/view commands

Syntax

observe.blocks(oA);

Description

Object oA is prevented from crossing over conditional barriers (pixels set to colour 1 on the priority screen) and borders of blocks set up with the block command.

See also

ignore.blocks

block

Controlling obstacles


block

Category

Object/view commands

Syntax

block(X1,Y1,X2,Y2);

Description

This sets up an invisible rectangular block on the screen with top-left co-ordinates X1,Y1 and bottom-right co-ordinates X2,Y2. Objects are not allowed to cross the borders of this block (unless they are told to ignore blocks). The block can be removed using the unblock command.

Note: You can only have one block on the screen at a time. If a block already exists, and you use the block command again, the new block will be there but the old one will be gone.

See also

unblock

ignore.blocks

observe.blocks

Controlling obstacles


unblock

Category

Object/view commands

Syntax

unblock();

Description

This removes the block set up on the screen by the block command.

See also

block

Controlling obstacles


get

Category

Inventory item commands

Syntax

get(iITEM);

Description

The room number of inventory item iITEM is set to 255, placing the item in the player’s inventory.

See also

get.v


get.v

Category

Inventory item commands

Syntax

get.v(vITEM);

Description

The room number of inventory item vITEM is set to 255, placing the item in the player’s inventory.

See also

get


drop

Category

Inventory item commands

Syntax

drop(iITEM);

Description

The room number of inventory item iITEM is set to 0.

See also


put

Category

Inventory item commands

Syntax

put(iITEM,ROOM);

Description

The room number of inventory item iITEM is set to ROOM.

See also

put.v


put.v

Category

Inventory item commands

Syntax

put.v(vITEM,vROOM);

Description

The room number of inventory item vITEM is set to vROOM.

See also

put


get.room.v

Category

Inventory item commands

Syntax

get.room.v(vITEM,vROOM);

Description

vROOM is set to the room number of inventory item vITEM.

See also


load.sound

Category

Sound commands

Syntax

load.sound(SOUNDNO);

Description

Sound SOUNDNO is loaded into memory.

See also

sound


sound

Category

Sound commands

Syntax

sound(SOUNDNO,fDONEFLAG);

Description

Sound SOUNDNO is played. fDONEFLAG is reset when the command is issued, and set when the sound finishes playing or is stopped with the stop.sound command.

The sound must be loaded before it is played. This can be done with the load.sound command.

See also

load.sound

stop.sound


stop.sound

Category

Sound commands

Syntax

stop.sound();

Description

If a sound is playing, it is stopped. The flag that was given as the second parameter of the sound command is set when this happens.

See also

sound


print

Category

Display commands

Syntax

print(mA);

Description

Message A is displayed in a window. If f15 is not set, then the window remains for 1/2 * v21 seconds (provided v21 is greater than 0) or until a key is pressed. If f15 is set, then the window remains until a close.window command is issued.

See also

print.v

print.at

print.at.v

close.window


print.v

Category

Display commands

Syntax

print.v(vA);

Description

Message number vA is displayed in a window. If f15 is not set, then the window remains for 1/2 * v21 seconds (provided v21 is greater than 0) or until a key is pressed. If f15 is set, then the window remains until a close.window command is issued.

See also

print

print.at

print.at.v

close.window


display

Category

Display commands

Syntax

display(ROW,COLUMN,mMESSAGE);

Description

Displays the text of message mMESSAGE at the specified row and column.

See also

display.v

set.text.attribute


display.v

Category

Display commands

Syntax

display(vROW,vCOLUMN,vMESSAGE);

Description

Displays the text of message number vMESSAGE at the location determined by the values of vROW and vCOLUMN.

See also

display

set.text.attribute


clear.lines

Category

Display commands

Syntax

clear.lines(TOP,BOTTOM,COLOUR);

Description

Clears the lines from TOP to BOTTOM with the colour COLOUR. I have found that it will only use black (if COLOUR is 0) or white (if COLOUR is greater than 0).

See also

clear.text.rect


text.screen

Category

Display commands

Syntax

text.screen();

Description

Switches the interpreter to text mode (40x25). This should only be used to display text on screen, and not to use menus, print statements, receive commands from the player or manipulate graphics as it does not have proper support for these things. It is handy for displaying text on a blank screen because you do not lose the graphics screen when you use it.

Once you have finished in text mode, you should use the graphics command to switch back.

See also

graphics


graphics

Category

Display commands

Syntax

graphics();

Description

Switches the interpreter back to graphics mode if it was previously switched to text mode (using the text.screen command).

See also

text.screen


set.cursor.char

Category

Display commands

Syntax

set.cursor.char(mCHAR);

Description

The cursor character (the character displayed at the end of the player input line) is set to the first character of message mCHAR.

See also


set.text.attribute

Category

Display commands

Syntax

set.text.attribute(FG,BG);

Description

Sets the foreground and background colours for display and display.v. The background colour can only be black (if BG is 0) or white (if BG is greater than 0). If the background is white, all text will be displayed with a black foreground. Otherwise, the text will be displayed with the foreground specified by FG (0-15).

See also

display

display.v


shake.screen

Category

Display commands

Syntax

shake.screen(A);

Description

Shakes the screen A times.

See also


configure.screen

Category

Display commands

Syntax

configure.screen(PLAYTOP,INPUTLINE,STATUSLINE);

Description

Sets the location of certain items on screen:

PLAYTOP is the top line of the playing area. This is normally set to 1. It should always be set to something between 0 and 3, since the playing area is 168 pixels high (21 lines) and should not go off the screen.

INPUTLINE is the line on which the player is prompted for input. This is normally set to 22.

STATUSLINE is the line on which the current score and sound on/off status are displayed. This is normally set to 0.

Note that the menu always appears on line 0.

See also

status.line.on

status.line.off


status.line.on

Category

Display commands

Syntax

status.line.on();

Description

Turns the status line on. The status line is usually on the top line of the screen (although this can be changed with configure.screen), and displays the current score and sound on/off status.

See also

status.line.off

configure.screen


status.line.off

Category

Display commands

Syntax

status.line.off();

Description

Turns the status line off. The status line is usually on the top line of the screen (although this can be changed with configure.screen), and displays the current score and sound on/off status. When it is turned off, the line is blank.

See also

status.line.on

configure.screen


set.string

Category

String commands

Syntax

set.string(sA,mB);

Description

Sets string sA to message mB.

See also


get.string

Category

String commands

Syntax

get.string(sA,mB,Y,X,L);

Description

The user is prompted to enter a string. Message mB is used as the prompt, and displayed at column Y, row X. The maximum string length is L. Once the string has been entered, it is stored in string sA.

See also

get.num


word.to.string

Category

String commands

Syntax

word.to.string(wA,sB);

Description

This command is supposed to convert a word to a string, but I have not been able to get it to work.

See also


parse

Category

String commands

Syntax

parse(sA);

Description

Parses string sA as if it were entered by the player.

See also


get.num

Category

Mathematical commands

Syntax

get.num(mPROMPT,vNUM);

Description

The player is prompted to enter a number, with the prompt being mPROMPT. vNUM is set to the number the player entered. If no valid number number is entered, this is 0.

See also

get.string


prevent.input

Category

System commands

Syntax

prevent.input();

Description

Hides the input prompt and prevents the player from entering input.

See also

accept.input


accept.input

Category

System commands

Syntax

accept.input();

Description

Allows the player to enter input, if they have been prevented from doing so. If the input prompt is hidden, it is displayed again (including any text that was on it).

See also

prevent.input


set.key

Category

Menu/Key commands

Syntax

set.key(nCODE1,CODE2,cA);

Description

The key determined by the combination of nCODE1 and nCODE2 is assigned to controller cA. You can assign multiple menu items and keys to the one controller, for example most game functions like save, restore, quit etc. usually have both a menu item and a key.

To assign a key by it’s ASCII code, set nCODE1 to the ASCII code you need (these can be obtained from an ASCII chart) and leave nCODE2 as 0. There are a few special codes:

nCODE1	Key
1-26	CTRL-A-Z
8	Backspace (CTRL-H)
9	Tab (CTRL-I)
13	Enter (CTRL-M)
27	Esc
32	Space

However, there are some keys and key combinations which use extended codes. For these, nCODE1 should be 0 and nCODE2 should be one of the values listed below (these are all standard PC-Keyboard codes, taken from the Epson GW-BASIC 3.20 manual.)

nCODE2	Key
3	CTRL-@
15	SHIFT-TAB
16-25	ALT-Q W E R T Y U I O P
30-38	ALT-A S D F G H J K L
44-50	ALT-Z X C V B N M
59-68	F1-F10
71	HOME*
72	UP*
73	PAGE UP*
75	LEFT*
77	RIGHT*
79	END*
80	DOWN*
81	PAGE DOWN*
82	INS
83	DEL
84-93	SHIFT-F1-F10
94-103	CTRL-F1-F10
104-113	ALT-F1-F10
115	CTRL-LEFT
116	CTRL-RIGHT
117	CTRL-END
118	CTRL-PAGE DOWN
119	CTRL-HOME
120-131	ALT-1 2 3 4 5 6 7 8 9 - =
132	CTRL-PAGE UP
133-134	F11 F12**
135-136	SHIFT-F11 F12**
137-138	CTRL-F11 F12**
139-140	ALT-F11 F12**

* - These codes can not actually be assigned as they are used for moving ego around, but were listed here for completeness.

** - I was not able to get these codes to work.

See also

Setting up menus and keys


add.to.pic

Category

Object/view commands

Syntax

add.to.pic(VIEWNO,LOOPNO,CELNO,X,Y,PRI,MARGIN);

Description

This command allows you to add a view to the visual picture screen in memory. Cel CELNO of loop LOOPNO of view VIEWNO is drawn on the picture at X,Y with a priority of PRI. If MARGIN is 0, 1, 2 or 3, the base line of the object (the bottom row of pixels of the cel) is given a priority of MARGIN. Since priority is taken into account, so you can use add.to.pic to add views behind other parts of the picture.

Note that the view must be loaded before you use it with add.to.pic. This can be done with the load.view command.

See also

add.to.pic.v


add.to.pic.v

Category

Object/view commands

Syntax

add.to.pic.v(vVIEWNO,vLOOPNO,vCELNO,vX,vY,vPRI,vMARGIN);

Description

This command allows you to add a view to the visual picture screen in memory. Cel vCELNO of loop vLOOPNO of view vVIEWNO is drawn on the picture at vX,vY with a priority of vPRI. If vMARGIN is 0, 1, 2 or 3, the base line of the object (the bottom row of pixels of the cel) is given a priority of vMARGIN. Since priority is taken into account, so you can use add.to.pic.v to add views behind other parts of the picture.

Note that the view must be loaded before you use it with add.to.pic.v. This can be done with the load.view command.

See also

add.to.pic


status

Category

Inventory item commands

Syntax

status();

Description

Displays the inventory screen. This is a text mode screen with the text “You are carrying:” on the top line and a list of the items in the player’s inventory (those with a room number of 255) below. If there are no items in the players inventory, “nothing” is displayed.

See also


save.game

Category

System commands

Syntax

save.game();

Description

Saves the game, which basically means writing all the information about the current status of everything in the game to a file so that it can be restored later. The user is prompted for a saved game directory, and then is asked to choose from one of 12 save game slots to save the game in.

See also

restore.game


restore.game

Category

System commands

Syntax

restore.game();

Description

Restores the game, which basically means reading information from a file (which was saved earlier) about the current status of everything in the game. The user is prompted for a saved game directory, and then chooses from up to 12 available saved games.

See also

save.game


init.disk

Category

System commands

Syntax

init.disk();

Description

This command was presumably used to format a floppy disk (for saved game purposes) on Apple II and other versions of the interpreter. On the PC version, this command does nothing.

See also


restart.game

Category

System commands

Syntax

restart.game();

Description

Restarts the game, taking the player back to the beginning.

See also


show.obj

Category

Inventory item commands

Syntax

show.obj(VIEWNO);

Description

Cel 0 of loop 0 of view VIEWNO is shown at the bottom of the screen, with the view’s description displayed above. Both dissapear when a key is pressed. The view does not need to be loaded in order to use this command.

The command does not actually have anything to do with screen objects (which are normally referred to as just “objects”). It is meant for when the player examines an inventory item - each item should have a view with a picture of it and a description, which is displayed using show.obj when the player examines it. Inventory items were sometimes called “objects”, which is why the command was called show.obj.

See also

show.obj.v


random

Category

Mathematical commands

Syntax

random(A,B,vC);

Description

The value of vC is set to a random number between A and B. If A is greater than B, then the number chosen is in the 0-255 range.

See also


program.control

Category

System commands

Syntax

program.control();

Description

Prevents the player from moving ego (object 0) around with the arrow keys. After this command has been executed, ego can only be moved by using the various object movement commands that are available such as move.obj. If ego is already moving, it continues in it’s current direction.

The player can be given control of ego again by using the player.control command.

See also

player.control


player.control

Category

System commands

Syntax

player.control();

Description

Allows the player to move ego (object 0) around with the arrow keys, after they have been prevented from doing so by the program.control command.

See also

program.control


obj.status.v

Category

Debugging commands

Syntax

obj.status.v(oA);

Description

Shows stats about an object - it’s co-ordinates, size, priority and step size.

See also

Objects


quit

Category

System commands

Syntax

quit(nCONFIRM);

Description

Quits the game. If nCONFORM is 1, then the game will quit instantly. If nCONFIRM is 0 (or anything else), the user will be prompted first.

See also


show.mem

Category

Debugging commands

Syntax

show.mem();

Description

Shows memory stats:

heapsize: Amount of available memory

now: Currently used memory

max: Maximum amount of memory that has been used

rm.0, etc: ?

max script: maximum script size (click here for more info)

See also


pause

Category

System commands

Syntax

pause();

Description

Pauses the game. This appears to be the same as the following command:

print("      Game paused.\n"

      "Press Enter to continue.");

See also

print


echo.line

Category

System commands

Syntax

echo.line();

Description

The previous line of input entered by the player is added to the input line (if there is already text on the input line, only the characters from the previous line after the number of characters currently on the line are added).

See also


cancel.line

Category

System commands

Syntax

cancel.line();

Description

Clears any text that is on the input line.

See also


init.joy

Category

System commands

Syntax

init.joy();

Description

Calibrates the joystick, if there is one connected to the computer.

See also


toggle.monitor

Category

System commands

Syntax

toggle.monitor();

Description

Switched between CGA and RGB graphics modes. This is only useful when the interpreter is running in one of these modes (either it is running on a computer with a CGA graphics adapter or the interpreter has been loaded with the -C or -R parameters). Note that although Sierra’s DOS interpreter will run in these modes, newer interpreters may not.

This command does not really have any practical use. It was available from a menu item in Sierra’s AGI games (the menu item was only present when running in these modes). The template game does not include this menu item, however. If you do want to run the game in these modes, just type “sierra -c” or “sierra -r” at the DOS prompt (assuming you are using Sierra’s interpreter). CGA mode uses the black-cyan-magenta-white CGA colour palette while RGB mode uses the blue-yellow-red-green CGA palette.

See also


version

Category

Debugging commands

Syntax

version();

Description

Displays the interpreter version.

See also


script.size

Category

System commands

Syntax

script.size(SIZE);

Description

The maximum script size is set to SIZE. For more information, click here

See also


set.game.id

Category

System commands

Syntax

set.game.id(mID);

Description

Sets the game ID to mID. This is a short name, up to 6 characters, that identifies the game, such as KQ2, SQ2, GR, MG etc. When the game ID is set like this, the interpreter checks it agains it’s own internal game ID and if they don’t match, it quits. This was to make sure games weren’t run with the wrong interpreter. Once the game ID is set, saved games include it in their filenames (e.g. SQSG.1).

There is a simple way around the game ID checking problem - simply don’t use this command, and the interpreter won’t find the wrong one and quit. This is especially important with new games, so that they can be run using interpreters from different games, which of course will have different IDs (although they must be the right interpreter version). Saved games will just be called SG.1, SG.2 etc. but that is not a real problem.

See also


log

Category

Debugging commands

Syntax

log(mLOGMESSAGE);

Description

Writes the current room number (value of v0), the input line given by the player and message mLOGMESSAGE to a file called ‘logfile’ in the game’s directory.

See also


set.scan.start

Category

Control flow commands

Syntax

set.scan.start();

Description

Tells the intepreter to start execution of this logic from the current point, instead of from the start of the logic.

See also

reset.scan.start


reset.scan.start

Category

Control flow commands

Syntax

reset.scan.start();

Description

Tells the interpreter to start execution of the logic from the start of the logic.

See also

set.scan.start


reposition.to

Category

Object/view commands

Syntax

reposition.to(oA,X,Y);

Description

The position on the screen of object oA is changed to X,Y. The reposition.to command should be used for objects that are currently on the screen. reposition.to does the same job as position, but it erases the object before moving it and draws it again afterwards.

See also

reposition.to.v

reposition

position

position.v

Positioning objects


reposition.to.v

Category

Object/view commands

Syntax

reposition.to.v(oA,vX,vY);

Description

The position on the screen of object oA is changed to vX,vY. The reposition.to command should be used for objects that are currently on the screen. reposition.to.v does the same job as position.v, but it erases the object before moving it and draws it again afterwards.

See also

reposition.to

reposition

position

position.v

Positioning objects


trace.on

Category

Debugging commands

Syntax

trace.on();

Description

Turns trace mode on. This does the same thing as the player pressing the SCROLL LOCK key.

Trace mode must be enabled (by setting flag 10) before using this command.

See also

trace.info

Trace mode


trace.info

Category

Debugging commands

Syntax

trace.info(LOGNUM,TOP,HEIGHT);

Description

Sets up trace mode. LOGNUM is the number of the logic containing trace commands. TOP and HEIGHT are the top line number of the trace window and the number of lines it takes up.

This command should be used before trace mode is enabled or turned on.

See also

trace.on

Trace mode


print.at

Category

Display commands

Syntax

print.at(mA,X,Y,W);

Description

Message A is displayed in a window with top left coordinates of X,Y and width W. If f15 is not set, then the window remains for 1/2 * v21 seconds (provided v21 is greater than 0) or until a key is pressed. If f15 is set, then the window remains until a close.window command is issued.

See also

print

print.v

print.at.v

close.window


print.at.v

Category

Display commands

Syntax

print.at.v(vA,vX,vY,vW);

Description

Message number vA is displayed in a window with top left coordinates of vX,vY and width vW. If f15 is not set, then the window remains for 1/2 * v21 seconds (provided v21 is greater than 0) or until a key is pressed. If f15 is set, then the window remains until a close.window command is issued.

See also

print

print.v

print.at

close.window


discard.view.v

Category

Object/view commands

Syntax

discard.view.v(vVIEWNUM);

Description

View vVIEWNUM is discarded from memory. If the view is not already loaded, the interpreter generates an error. Make sure you do not have the view assigned to any objects before you discard it.

See also

discard.view

load.view

load.view.v


clear.text.rect

Category

Display commands

Syntax

clear.text.rect(Y1,X1,Y2,X2,COLOUR);

Description

Clears the text rectangle with a top-left corner of X1,Y1 and a bottom-right corner of X2,Y2 with the colour COLOUR. I have found that it will only use black (if COLOUR is 0) or white (if COLOUR is greater than 0).

See also

clear.lines


set.upper.left

Category

Object/view commands

Syntax

set.upper.left(A,B);

Description

The purpose of this command is not currently known.

See also


set.menu

Category

Menu/Key commands

Syntax

set.menu(mNAME);

Description

Tells the interpreter to create a menu with the name mNAME. One or more set.menu.item commands should follow, which add items to that menu.

See also

set.menu.item

Setting up menus and keys


set.menu.item

Category

Menu/Key commands

Syntax

set.menu.item(mNAME,cA);

Description

Adds an item with the name mNAME to the menu previously created using the set.menu command. The item is assigned to controller cA, so when the user selects it from the menu the test command controller(cA) will be true.

See also

set.menu.item

Setting up menus and keys


submit.menu

Category

Menu/Key commands

Syntax

submit.menu();

Description

Initializes the menus set up with the set.menu and set.menu.item commands, allowing them to be used. This command can only be used once, and after that the menus can not be changed.

See also

set.menu

set.menu.item

Setting up menus and keys


enable.item

Category

Menu/Key commands

Syntax

enable.item(cA);

Description

Enables the menu item that is assigned to controller cA.

All menu items are enabled again whenever the game is restarted.

See also

disable.item


disable.item

Category

Menu/Key commands

Syntax

disable.item(cA);

Description

Disables the menu item that is assigned to controller cA.

All menu items are enabled again when the game is restarted, so if there are any items that need to be disabled permenantly (such as seperators) then they should be disabled again when the game is restarted.

See also

enable.item


menu.input

Category

Menu/Key commands

Syntax

menu.input();

Description

This brings up the menu at the end of the current interpreter cycle. The next cycle does not start until the user has selected an item from the menu, or pressed ESC to exit the menu.

Flag 14 (or menu_enabled in the template game) must be set for this command to work.

ESC is usually the key that activates the menu, but this is not built in to the interpreter so do do this you need assign the ESC key to a controller using set.key, and then test for that controller to activate the menu (this is already done in the template game).

See also

Settings up menus and keys


show.obj.v

Category

Inventory item commands

Syntax

show.obj.v(vVIEWNO);

Description

Cel 0 of loop 0 of view vVIEWNO is shown at the bottom of the screen, with the view’s description displayed above. Both dissapear when a key is pressed. The view does not need to be loaded in order to use this command.

The command does not actually have anything to do with screen objects (which are normally referred to as just “objects”). It is meant for when the player examines an inventory item - each item should have a view with a picture of it and a description, which is displayed using show.obj when the player examines it. Inventory items were sometimes called “objects”, which is why the command was called show.obj.

See also

show.obj


open.dialogue

Category

Display commands

Syntax

open.dialogue();

Description

This command supposedly enables the get.string and get.num commands when the prevent.input command has been used, but they seem to be enabled anyway so I am not sure what the command actually does.

See also

close.dialogue


close.dialogue

Category

Display commands

Syntax

close.dialogue();

Description

This command supposedly disables the get.string and get.num commands when the prevent.input command has been used, but it does not seem to do this so I am not sure what the command actually does.

See also

open.dialogue


mul.n

Category

Mathematical commands

Syntax

mul.n(vA,B);

vA *= B;

vA = vA * B;

Description

vA is multiplied by B. Since a var can only be from 0-255, if the result is greater than 255, then the value “wraps around”, e.g. 100 * 3 would give 44.

See also

mul.v


mul.v

Category

Mathematical commands

Syntax

mul.v(vA,vB);

vA *= vB;

vA = vA * vB;

Description

vA is multiplied by vB. Since a var can only be from 0-255, if the result is greater than 255, then the value “wraps around”, e.g. 100 * 3 would give 44.

See also

mul.n


div.n

Category

Mathematical commands

Syntax

div.n(vA,B);

vA /= B;

vA = vA / B;

Description

vA is divided by B. The result is rounded down. If you divide by 0, the interpreter will crash.

See also

div.v


div.v

Category

Mathematical commands

Syntax

div.n(vA,vB);

vA /= vB;

vA = vA / vB;

Description

vA is divided by vB. The result is rounded down. If you divide by 0, the interpreter will crash.

See also

div.n


close.window

Category

Display commands

Syntax

close.window();

Description

If a window is left on the screen from a print command, it is removed.

See also

print

print.v

print.at

print.at.v


unknown170

Category

Unknown commands

Syntax

unknown170(A);

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown171

Category

Unknown commands

Syntax

unknown171();

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown172

Category

Unknown commands

Syntax

unknown172();

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown173

Category

Unknown commands

Syntax

unknown173();

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown174

Category

Unknown commands

Syntax

unknown174(A);

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown175

Category

Unknown commands

Syntax

unknown175(A);

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown176

Category

Unknown commands

Syntax

unknown176();

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown177

Category

Unknown commands

Syntax

unknown177(A);

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown178

Category

Unknown commands

Syntax

unknown178()

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown179

Category

Unknown commands

Syntax

unknown179(A,B,C,D);

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown180

Category

Unknown commands

Syntax

unknown180(2);

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


unknown181

Category

Unknown commands

Syntax

unknown181();

Description

The purpose and proper name of this command is not known.

The reason for the name not being known is that the command names were obtained from the trace logic found in some games, which gives a list of commands used by the built-in trace mode. This list must have been created at a time when there were 169 commands, because commands 170 and above were not listed there. Once someone works out what the command does, a name will be made up for it.

The number of paramaters is known, but not the type of parameters. Therefore, the parameters in the unknown commands are all set to numbers at present.

See also


equaln

Category

Test commands / Mathematical commands

Syntax

if (equaln(vA,B)) { .....

if (vA == B) { .....

Description

Returns true if vA is equal to B.

See also

equalv


equalv

Category

Test commands / Mathematical commands

Syntax

if (equalv(vA,vB)) { .....

if (vA == vB) { .....

Description

Returns true if vA is equal to vB.

See also

equaln


lessn

Category

Test commands / Mathematical commands

Syntax

if (lessn(vA,B)) { .....

if (vA < B) { .....

Description

Returns true if vA is less than B.

See also

lessv


lessv

Category

Test commands / Mathematical commands

Syntax

if (lessn(vA,vB)) { .....

if (vA < vB) { .....

Description

Returns true if vA is less than vB.

See also

lessn


greatern

Category

Test commands / Mathematical commands

Syntax

if (greatern(vA,B)) { .....

if (vA > B) {

Description

Returns true if vA is greater than B.

See also

greaterv


greaterv

Category

Test commands / Mathematical commands

Syntax

if (greaterv(vA,vB)) { .....

if (vA > vB) { .....

Description

Returns true if vA is greater than vB.

See also

greatern


isset

Category

Test commands / Flag commads

Syntax

if (isset(fA)) { .....

if (fA) { .....

Description

Returns true if flag fA is set.

See also

issetv


issetv

Category

Test commands / Flag commads

Syntax

if (isset(vA)) { .....

Description

Returns true if the flag determined by the value of vA is set.

See also

isset


has

Category

Test commands / Inventory item commands

Syntax

if (has(iA)) { .....

Description

Returns true if the inventory item iA is in the player’s inventory (i.e. the item’s room number is 255).

See also

obj.in.room


obj.in.room

Category

Test commands / Inventory item commands

Syntax

if (obj.in.room(iA,vB)) { .....

Description

Returns true if the room number if inventory item iA is equal to vB.

See also

has


posn

Category

Test commands / Object/view commands

Syntax

if (posn(oA,X1,Y1,X2,Y2)) { .....

Description

Returns true if the co-ordinates of the bottom-left pixel of object oA are within the region (X1,Y1,X2,Y2).

See also

right.posn

center.posn

obj.in.box


controller

Category

Test commands / Menu/Key commands

Syntax

if (controller(cA)) { .....

Description

Returns true if the menu item or key assigned to controller cA has been selected or pressed during the current cycle.

See also

Setting up menus and keys


have.key

Category

Test commands

Syntax

if (have.key()) { .....

Description

Returns true if the user has pressed a key.

See also


said

Category

Test commands

Syntax

if (said(“word1”,”word2”....”wordn”)) { .....

Description

The said test command is different to all other commands in the language in that it accepts a special type of parameter and can have any number of parameters. It is used to test if the player has entered certain words.

First, the process of parsing player input needs to be explained. When the player enters a command, the interpreter does the following things with it:

•	Removes certain punctuation characters

•	Assigns each word entered a number starting from 1. When doing this, it tries to find the longest sequence of characters that match a word in the WORDS.TOK file (so for example if the words “door”, “knob” and “door knob” were in the WORDS.TOK file and the player entered “turn door knob” then the words would be “turn” and “door knob” instead of “turn”, “door” and “knob”). Words in group 0 (usually things like “a”, “my”, “the”) are skipped (not assigned numbers).

•	If one or more words that are not in the WORDS.TOK file are found, it will set v9 (unknown_word_no in the template game) to the first unknown word.

Note: The above is based purely on observation. I am not sure if the interpreter does exactly this, or in this order.

Once the player input has been received, flag 2 (input_recieved in the template game) is set and flag 4 (input_parsed in the template game) is reset.

When the said test command is used, it goes through each word given as a parameter and compares it with the corresponding word entered by the player. If they are the same (or are in the same word group), then it continues onto the next word. The comparison is not case sensitive. If all the words are the same, and there are no entered words left over, then the said command returns true and sets flag 4.

There are a couple of special word groups:

Word group 1: “anyword” - if this word is given as a parameter, then any word will do. So if you test for said(“eat”,”anyword”) then the result will be true if the player enters “eat cake”, “eat chocolate”, “eat worm”, “eat sword”, etc.

Word group 9999: “rol” (rest of line) - this means the rest of the line. If you test for said(“kill”,”rol”) then the result will be true if the player enters “kill lion”, “kill lion with sword”, etc.

See also


compare.strings

Category

Test commands / String commands

Syntax

if (compare.strings(s1,s2)) { .....

Description

Compares strings s1 and s2 and returns true if they are the same. The comparison is not case-sensitive, and some characters such as space and exclamation marks are ignored.

See also


obj.in.box

Category

Test commands / Object/view commands

Syntax

if (obj.in.box(oA,X1,Y1,X2,Y2)) { .....

Description

Returns true if all of the bottom row of pixels of object oA are within the region (X1,Y1,X2,Y2).

See also

posn

right.posn

center.posn


center.posn

Category

Test commands / Object/view commands

Syntax

if (center.posn(oA,X1,Y1,X2,Y2)) { .....

Description

Returns true if the co-ordinates of the bottom-middle pixel of object oA are within the region (X1,Y1,X2,Y2).

See also

posn

right.posn

obj.in.box


right.posn

Category

Test commands / Object/view commands

Syntax

if (right.posn(oA,X1,Y1,X2,Y2)) { .....

Description

Returns true if the co-ordinates of the bottom-right pixel of object oA are within the region (X1,Y1,X2,Y2).

See also

posn

center.posn

obj.in.box


Drawing pictures

In order to draw a picture on the screen, you should use the following commands in the correct order:

load.pic(vA);

draw.pic(vA);

discard.pic(vA);

..

show.pic();

The interpreter stores two different screens in memory - the visual screen and the priority screen. When you use the first three commands above, you are updating both of these screens in memory. However, you are not updating what is displayed on the actual screen that the player sees. This is only done when the show.pic command is used. You should do this directly after the first three commands, unless you need to also set up some screen objects in between.

The reason the first parameter of load.pic, draw.pic and discard.pic is a variable is because most times these commands are used, the parameter given is v0 (the current room number). Most rooms you see will have the following at the start:

load.pic(v0);

draw.pic(v0);

discard.pic(v0);

If you want to load a picture other than the current room number, you will need to set the value of a variable to that number and then give the variable as the parameter.

See also

load.pic

draw.pic

overlay.pic

discard.pic

show.pic


Objects

Objects (sometimes as referred to as “screen objects”, and not to be confused with “inventory objects”) are what provide the animation in AGI games. They can represent various things such as characters, background animations or still props. Each object has a view assigned to it, and can be placed anywhere on screen and moved around.

Object 0, commonly referred to as “ego”, is special. This is the object that the player moves around using the arrow keys.

Topics

Initializing objects

Cycling objects

Positioning objects

Moving objects

Controlling obstacles

Priorities

See also

Object/view commands


Initializing objects

In order to initialize a screen object you must follow these steps:

1. 	Animate the object. This is done using the animate.obj command. This tells the interpreter that you want to use this object. There are a limited number of objects that the interpreter can use at any one time. This is set by a certain byte in the OBJECT file. There is currently no program that will edit this, but the template game allows for up to 16 objects (0-15) which should be enough. Also, the more objects you use the slower the interpreter will run, but it is not really noticeable on today’s machines.

2. 	Assign a view to the object. This is done using the set.view command. Each object must have a view assigned to it, and this is the view that is displayed on the screen wherever the object is. One view can be assigned to multiple screen objects. You must have the view loaded in memory before you assign it. This can be done with the load.view command.

3. 	Position the object on screen. This is done using the position command.

4. 	Draw the object. This is done using the draw command. If you do not do this the object will not be visible on screen.

Here is an example:

animate.obj(o2);

load.view(4);

set.view(o2,4);

position(o2,80,120);

draw(o2);

This will result in an animation of view 4 being displayed at 80,120.

See also

Objects


Cycling objects

The animation of an object is called “cycling”. This is the successive display of several cels from the same loop in order. When you initialize an object, it cycles the cels in the first loop (loop 0) by default. To change the loop number, use the set.loop command. To change the speed of cycling, use the cycle.time command. If you want to display a single cel without animation, set the loop number and cel number you want to display using the set.loop and set.cel commands and then use the stop.cycling command (you can start cycling again by using the start.cycling command).

Here is an example of initializing an object that displays cel 2 of loop 1 without animating:

animate.obj(o2);

load.view(4);

set.view(o2,4);

position(o2,80,120);

set.loop(o2,1);

set.cel(o2,2);

draw(o2);

stop.cycling(o2);

The objects aren’t updated on screen until the start of the next cycle (or until the force.update command is issued), so whatever changes you make to an object’s position or appearance do not take affect till then.

Normally when an object is moving around, it’s loop number is determined by it’s direction:

Direction	Loop no
0 (not moving)	not changed
1 (up)	3 (if loop 2 and 3 exist) otherwise not changed
2 (up-right)	0
3 (right)	0
4 (down-right)	0
5 (down)	2 (if loop 2 and 3 exist) otherwise not changed
6 (down-left)	1 (if loop 1 exists) otherwise 0
7 (left)	1 (if loop 1 exists) otherwise 0
8 (up-left)	1 (if loop 1 exists) otherwise 0

The direction is only chosen automatically if there are less than 5 loops in the view assigned to the object.

To stop the interpreter from chosing a loop number based on the object’s direction, use the fix.loop command. To let it chose the loop number, use the release.loop command.

To play the animation in reverse, use the reverse.cycle command. To play it forwards again, use the normal.cycle command.

To play the animation once and then stop cycling, use the end.of.loop or reverse.loop commands.

See also

set.loop

set.loop.v

set.cel

set.cel.v

cycle.time

start.cycling

stop.cycling

force.update

normal.cycle

reverse.cycle

end.of.loop

reverse.loop

Objects


Positioning objects

There are five commands which allow you to position objects on screen:

position

position.v

reposition

reposition.to.v

reposition

Also, the get.posn command will store an object’s position in two variables.

Note: The position of an object is always taken from it’s bottom-left corner.

See also

Objects


Moving objects

Each object on screen has a direction it is moving in. This is a numerical value from 0 to 8:

When an object is moving normally (and has a direction greater than 0), it will continue moving until it is told to stop, move in another direction, or runs into an obstacle (such as a control line, a block, or another object).

An object’s direction can be changed using the set.dir command. The get.dir command will allow you to find out what it’s current direction is. The direction of ego (object 0) is always stored in v6. To stop an object’s movement, use stop.motion.

There are several commands which will make an object move in different ways:

move.obj/move.obj.v

wander

follow.ego

The normal.motion command will make the object in move in the way described above after it has been moving from one of these three commands.

An object’s step size (the number of pixels moved each step) and step time (the number of interpreter cycles between steps) can be set with the step.size and step.time commands.

See also

set.dir

get.dir

stop.motion

start.motion

move.obj

move.obj.v

wander

follow.ego

normal.motion

step.size

step.time

Objects


Controlling obstacles

There are five main ways an object’s movement around the screen can be limited:

•	Control lines on the priority screen

•	Blocks

•	Land/water

•	The horizon

•	Other objects

For any of these, no part of the object’s baseline (the bottom row of pixels of the object) can be on a part of the screen the object is not allowed on.

Control lines on the priority screen

On the priority screen, the first four colours (0-3) have special meaning. Colour 0 (black) is an unconditional barrier. No object is ever allowed to be on parts of the screen with a pixel of this colour in the priority screen.

Colour 1 (dark blue) is a conditional barrier. Objects are not normally allowed to be on a conditional barrier, unless the ignore.blocks command is used to allow them to do so.

Colour 2 (dark green) is a signal barrier. This can be used to test if ego is walking into a certain place. Whenever ego is touching a signal barrier, flag 3 is set.

Colour 3(dark cyan) signifies water. This is explained shortly.

Blocks

You can set up an invisible rectangular block on the screen using the block command. The interpreter will not allow objects to cross the borders of the block (unless they are told to ignore blocks). You can remove the block using the unblock command. Objects can be told to ignore blocks using the ignore.blocks command and be told to observe blocks by using the objserve.blocks command.

Land/water

Parts of the priority screen which are colour 3 (dark cyan) are considered to be “water”. If you look at the priority screen of rooms that have lakes or rivers in them, you will usually see this. Parts of the priority screen which are not colour 3 are considered to be “land”. You do not have to use colour 3 to represent water - it could also represent some other surface such as ice, lava, sand, a slippery floor, or whatever you need for that particular room.

Objects can be allowed only on water, only on land or on both. This is set be the object.on.water, object.on.land and object.on.anything commands.

Whenever ego’s baseline is completely on water, flag 0 is set.

The horizon

The horizon is an invisible horizontal line, usually near the top of the screen. It’s position is set using the set.horizon command.

Normally, objects can not go above the horizon. This can be changed using the ignore.horizon and observe.horizon commands.

Other objects

Objects are normally blocked by other objects on screen - that is, the baselines of objects are not allowed to touch each other. This can be changed, however, with the ignore.objs and observe.objs commands.

See also

block

unblock

ignore.blocks

objserve.blocks

object.on.water

object.on.land

object.on.anything

set.horizon

ignore.horizon

observe.horizon

ignore.objs

observe.objs

Objects


Priorities

The AGI screen is divided vertically into 12 priority bands (4-15). Objects with a higher priority are displayed on top of objects with a lower priority. Different parts of a picture can also be given different priorities. So something in the far distance would have a priority of 4 (everything else would go on top of this) and something right at the front of the screen would have a priority of 15 (nothing will go on top of this except objects with a priority of 15).

This is best explained graphically:

Here you can see both the visual and priority screens. As you can see, ego has a priority of 13 (magenta) but the bottom part of ego is on a part of the screen with a priority of 15 (white). Thus, that part of ego is not drawn. The floor and some of the walls have a priority of 4 (red) because nothing needs to be drawn behind them.

If the priority of an object and the part of the screen it is on are the same, the object goes on top. If two objects that have the same priority overlap, the object with the higher number goes on top.

Normally, the priority of an object is determined by it’s vertical position on screen:

Priority	Y Range
4	0-47
5	48-59
6	60-71
7	72-83
8	84-95
9	96-107
10	108-119
11	120-131
12	132-143
13	144-155
14	156-167
15	-

(note that 167 is the max. Y value an object can have)

To set an object’s priority so it will remain constant wherever the objects is on screen, use the set.priority or set.priority.v commands. To change it back so the priority is dependent on the object’s position, use the release.priority command.

An object’s priority can be determined using the get.priority command.

See also

set.priority

set.priority.v

release.priority

get.priority

Objects


Trace mode

The AGI Interpreter has a built in trace mode, which is useful for examining the operation of logics and tracking down problems. When it is turned on (either by the game issuing the trace.on command or by the player pressing the SCROLL LOCK key), a window is displayed on the screen showing commands and their parameters as they are executed.

Before trace mode is used, the trace.info command must be used to initialize trace mode. It is not necessary to use this, but if it is not used then the command names will not be displayed in the trace winow (only the command numbers). Flag 10 must be set in order to enable trace mode.

The user can then activate trace mode by using the SCROLL LOCK key. Pressing this key while trace mode is on will turn it off.

See also

trace.info

trace.on


Displaying text on screen

For text display purposes, the AGI screen consists of 25 lines (numbered 0-24) and 40 columns (numbered 0-39). Each text character is 8 screen pixels (4 AGI pixels) wide and 8 screen pixels high. Note that this gives a total screen resolution of 320x200, even though the area that pictures are displayed in and objects are placed is only 168 pixels high. The top line of the screen is normally reserved for the status line and menu, and the bottom three lines are normally reserved for player input and other text display (in some early versions of the interpreter, text from commands like print was displayed down here instead of in windows).

See also

Display commands


Types

There are 9 different types are accepted by AGI commands. Each argument in a command is of a certain type. For example, the first argument of the addn command is a variable and the second argument is a number.

When using an argument, you must give the prefix for the type before the actual number, e.g. v3 for variable 3. This is to make sure you know what type you are using.

Numbers

(no prefix)

These are integer values which can have a value from 0 to 255.

Variables (also known as “vars”)

Prefix: v

Each of these can contain an integer value from 0 to 255, thus being the AGI equivalent of a byte (or unsigned char). There are 256 variables (numbered from 0 to 255) available. Variables 0-26 have special meaning to the interpreter (click here for more info).

See also: Mathematical commands

Flags

Prefix: f

These can either be set or not set (some documentation refers to them of having a value of 0 or 1, 0 meaning not set and 1 meaning set). They are the AGI equivalent of a boolean type. There are 256 flags (numbered from 0 to 255) available. Flags 0-15 have special meaning to the interpreter (click here for more info).

See also: Flag commads

Messages

Prefix: m

Each logic can contain up to 255 messages, which are text that is used by commands like print to give the user information. Each message is numbered (starting from 1) and can be as long as you like. When you give a message as a parameter for a command, you can either use a specific message number or give the message surrounded by quote marks (and let the compiler give the message a number), e.g.:

print(“He’s not here.”);	- giving the actual message

print(m2);	- giving the message number

If you use the message number as in the second example, you must tell the compiler what that message will actually be. This is done using th message command:

#message 2 “He’s not here.”

You’re probably wondering why you would want to give a message a specific number. This is because you can refer to this in other message by using %m and then the message number, e.g:

print(“%m2 But he’ll be back soon.”);

The message is stored like this in the logic resource, but when the interpreter displays it it will replace %m2 with message 2, so the text “He’s not here. But he’ll be back soon.” will be displayed. Also, commands like print.v use a message number determined by the value of a variable, so when using these command you sometimes need to know the numbers of certain messages.

You can also include other things in messages:

%vN	Value of var N

%wN	Nth word that the player typed in

%sN	String N

%gN	Message N from logic 0

When using %v, you can place a | after the number and then another number which determines the minimum number of digits for the var. For example, if you use %v40|2 and the value of v40 is 8, then the %v40|2 will be replaced with 08. If the value of v40 was 100 or more, all three digits would be displayed.

These inclusions can also be used in the descriptions in view resources.

Objects

Prefix: o

For a description of objects, click here.

See also: Object/view commands

Inventory items

Prefix: i

Inventory items are things that the player can carry around with them. Their names are stored in the OBJECT file. A game contain up to 256 objects (numbered from 0-255). Each object used by the game must be present in the OBJECT file.

Every object has a room number which is a value from 0-255. If the room number is 255, it is in the player’s inventory.

See also: Inventory item commands

Strings

Prefix: s

Up to 12 different strings can be used by the game. These can be up to 40 characters long. The first character of string 0 is used as the prompt character (“>” or “]” in most games).

See also: String commands

Words

Prefix: w

These are the words that the player has typed in, starting from 1. This list of words does not include words that are in group 0 (usually things like “the”, “this”, “with” etc.). So if the player types “unlock the door with the key” then word 1 will be “unlock”, word 2 will be “door” and word 3 will be “key” (assuming “the” and “with” are in group 0). Words can be converted to strings with the word.to.string command.

Controllers

Prefix: c

These are menu and key events. You can assign a menu item or key to a controller and then test to see when that item was selected or that key was pressed.

See also: Setting up menus and keys


Setting up menus and keys

For a list of menu/key related commands, click here.

About controllers

A controller is an event that has occured due to the user selecting a menu item or pressing a key. There are 50 controllers available (numbered from 0-49), and menu items and keys are assigned to them. To test whether the event has occured, use the controller test command, like this:

if (controller(c2)) {

  quit(0);

}

The above example tests for controller 2 (which could be assigned to “quit” on the menu), and if it has occured, it quits the game.

Setting up menus

First use the set.menu command to create a menu. Then use the set.menu.item command to add items to it. Repeat this process until all the menus have been set up, and then use the submit.menu command to initialize it, making it available for use. Here is an example of creating a menu:

set.menu(“File”);

set.menu.item(“Restart”,c1);

set.menu.item(“Quit”,”c2);

set.menu(“Help”);

set.menu.item(“About);

submit.menu();

The second parameter of the set.menu.item command is the controller that the menu item is being assigned to. You can assign multiple menu items and keys to the one controller, for example most game functions like save, restore, quit etc. usually have both a menu item and a key.

The menu can be brought up using the menu.input command.

Setting up keys

Use the set.key command.


Special variables

Some variables have special meaning to the interpreter:

Var	Define name in template game	Description
0	room_no	Number of the current room
1	prev_room_no	Number of the previous room
2	ego_edge_code	Which edge of the screen ego is touching 0: not touching edge 1: horizon 2: right edge 3: bottom edge 4: left edge
3	score	Current score
4	object_touching_edge	Number of an object other than ego that is touching the edge.
5	object_edge_code	See ego_edge_code
6	ego_dir	Direction of ego’s motion (see Moving Objects for a list of directions).
7	max_score	Maxmimum score
8	free_memory	The number of 256-byte lots of free memory available for resources.
9	unknown_word_no	If the player has entered an unknown word, this is set to the number of that word (i.e. 2 if it’s the second word entered). Otherwise, this is 0.
10	cycle_delay	Delay between interpreter cycles (*1/20 second)
11	clock_seconds	Number of seconds on the interpreter’s clock (the clock is reset when the game starts).
12	clock_minutes	Number of minutes on the interpreter’s clock
13	clock_hours	Number of hours on the interpreter’s clock
14	clock_days	Number of days on the interpreter’s clock
15	joystick_sensitivity	Sensitivity of the joystick
16	ego_view_no	Number of the view assigned to ego
17	error_code	What type of error has occured
18	error_information	Extra information about the error
19	key_pressed	The ASCII code of the key that has just been pressed, if any
20	computer_type	Type of computer (0=PC)
21	window_close_time	Number of half-seconds to wait before closing a window (if 0, the window remains on screen until the user presses a key).
22	sound_type	Sound generator type. (PC=1,Tandy=3)
23	sound_volume	Volume of the sound
24	(unknown)	Always seems to be set to 41
25	selected_inventory_item	If the player has selected an inventory item from the inventory screen, this is set to the number of that item (or 255 if ESC was pressed).
26	video_mode	Video mode: 0: CGA (black-cyan-magenta-white CGA palette) 1: RGB (blue-yellow-red-green CGA palette) 2: Hercules 3: EGA 4: VGA

See also

Special flags


Special flags

Some flags have special meaning to the interpreter:

Flag	Define name in template game	Meaning (when set)
0	ego_on_water	This indicates that ego’s baseline (the bottom row of pixels) is completely on water (pixels with a priority of 3)
1	ego_hidden	Ego is completely hidden by something else on screen
2	input_received	Input has been recieved from the player
3	ego_touching_signal_line	All or part of ego’s basline (the bottom row of pixels) is touching a signal line (pixels with a priority of 2)
4	input_parsed	The input recieved from the player has been parsed (the said command has returned true at some point)
5	new_room	This is the the first cycle in a new room
6	game_restarted	This is the first cycle since the game has been restarted
7	script_buffer_blocked	Prevents the interpreter from writing to the script buffer
8	joystick_sensitivity_set	Indicates that v15 specifies the joystick sensitivity
9	sound_on	The sound is on
10	trace_enabled	Trace mode is enabled
11	first_logic0_cycle	This is the first time logic 0 has been executed
12	game_restored	This is the first cycle since a game has been restored
13	inventory_select_enabled	The player is allowed to select an inventory item in the inventory screen. When the item has been selected, v25 (selected_inventory_item) is set to the number of the item selected (or 255 if ESC is pressed).
14	menu_enabled	The menu is enabled
15	windows_remain	Windows created by print and similar commands remain on screen until the close.window command is used. If this flag is not set, the windows remain on screen until the user presses a key or for the time specified by v21 (window_close_time).

See also

Special variables


The script buffer

I am not completely sure exactly what the script buffer does or how it works. I believe it holds code that is stored in a saved game and then executed when the game is restored in order to put the interpreter in the same state of execution as it was when the game was saved. I suppose it would contain things like what resources have to be loaded, etc.

When you use certain commands, such as load.view and add.to.pic, they increase the current script size. This means that when you save the game, information about commands that have been used to set up the screen and other aspects of the game can be re-executed when the game is loaded. So if you use some of these commands repeatedly, they can exceed the maximum script buffer size and crash the interpreter. Therefore, it is important to keep an eye on the script size (this can be done with the show.mem command).

For example, I was working on a part of a game where the player walks through a door and a small room appears on the side of the screen. I was originally using overlay.pic to draw the room (and erase it again afterwards when the player walked out of it), but I noticed that if the player walked in and out of the room a few times the game would crash (with a “script buffer overflow” error). It turned out that every time the load.pic, overlay.pic and discard.pic commands were executed, the script size was increased and it eventually got too big. Instead, I decided to simply use a view for the room instead of overlaying a picture.

So the script buffer is something to watch out for and can be the cause of many problems if you are not aware of it. The maximum script size can be changed using the script.size command (the default size being 50), but this will not completely solve problems where the script size can be increaded by certain command being used repeatedly.


Logic syntax

Action Commands

Normal action commands are specified by the command name followed by brackets which contain the arguments, separated by commas. A semicolon is placed after the brackets. The brackets are required even if there are no arguments. The arguments given must have the correct prefix for that type of argument as explained later in this document (this is to make sure the programmer does not use a var, for example, when they think they are using a flag).

assign.v(v50,0);

program.control();

Multiple commands may be placed on the one line:

reset(f6); reset(f7);

Substitutions for the following action commands are available:

increment(v30);	v30++;

decrement(v30);	v30--;

assignn(v30,4);	v30 = 4;

assignv(v30,v32);	v30 = v32;

addn(v30,4);	v30 = v30 + 4;	or	v30 += 4;

addv(v30,v32);	v30 = v30 + v32;	or	v30 += v32;

subn(v30,4);	v30 = v30 - 4;	or	v30 -= 4;

subv(v30,v32);	v30 = v30 - v32;	or	v30 -= v32;

mul.n(v30,4);	v30 = v30 * 4;	or	v30 *= 4;

mul.v(v30,v32);	v30 = v30 * v32;	or	v30 *= v32;

div.n(v30,4);	v30 = v30 / 4;	or	v30 /= 4;

div.v(v30,v32);	v30 = v30 / v32;	or	v30 /= v32;

lindirectn(v30,4);	*v30 = 4;

lindirectv(v30,v32);	*v30 = v32;

rindirect(v30,v32);	v30 = *v32;

IF structures and test commands

An if structure looks like this:

if (<test commands>) {

  <action commands>

}

or like this :

if (<test commands>) {

  <action commands>

}

else {

  <more action commands>

}

Carriage returns are not necessary:

if (<test commands>) { <action Commands> } else { <more action commands> }

Test commands are coded like action commands except there is no semicolon. They are separated by && or || for AND or OR.

if (isset(f5) &&

    greatern(v5,6)) { ......

Again, carriage returns are not necessary within the if statement:

if (lessn(v5,6) && (greatern(v5,2)) { .......

if (isset(f90) && equalv(v32,v34)

    && greatern(v34,20)) { .......

A ! placed in front of a command signifies a NOT.

if (!isset(f7)) {

  ......

Boolean expressions are not necessarily simplified so they must follow the rules set down by the file format. If test commands are to be ORred together, they must be placed in brackets.

if ((isset(f1) || isset(f2)) {

  ......

if (isset(f1) && (isset(f2) || isset(f3))) {

  ......

if (isset(1) || (isset(2) && isset(3))) {    is NOT legal

Depending on the compiler, simplification of boolean expressions may be supported, so the above may not apply in all cases (although if these are rules are followed then the logic will work with all compilers).

Substitutions for the following test commands are available:

equaln(v30,4)	v30 == 4

equalv(v30,v32)	v30 == v32

greatern(v30,4)	v30 > 4

greaterv(v30,v32)	v30 > v32

lessn(v30,4)	v30 < 4

lessv(v30,v32)	v30 < v32

!equaln(v30,4)	v30 != 4

!equalv(v30,v32)	v30 != v32

!greatern(v30,4)	v30 <= 4

!greaterv(v30,v32)	v30 <= v32

!lessn(v30,4)	v30 >= 4

!lessv(v30,v32)	v30 >= v32

Also, flags can be tested for by just using the name of the flag:

if (f6) { .....

if (v7 > 0 && !f6) { .....

Argument types

There are 9 different types of arguments that commands use:

Number	(no prefix)

Var	(prefix "v")

Flag	(prefix "f")

Message	(prefix "m")

Object	(prefix "o")

Inventory Item	(prefix "i")

String	(prefix "s")

Word	(prefix "w")

Controller	(prefix "c")

The said test command uses it's own special arguments which will be described later.

Each of these types of arguments is given by the prefix and then a number from 0-255, e.g. v5, f6, m27, o2.

The word type is words that the player has typed in, not words that are stored in the WORDS.TOK file. Strings are the temporary string variables stored in memory, not to be confused with messages (that are stored in the logic resources). Controllers are menu items and keys.

Compilers can enforce type checking, so that the programmer must use the correct prefix for an argument so that they know they are using the right type. Decoders should display arguments with the right type.

move.obj(so4,80,120,2,f66);

if (obj.in.box(so2,30,60,120,40)) { .....

A complete list of the commands and their argument types is available as part of AGI Specs.

Messages and inventory items may be given in either numerical text format:

print("He's not here.");

print(m12);

if (has("Jetpack")) { .....

if (has(io9)) { .....

Messages can also be split over multiple lines:

print("This message is split "

      "over multiple lines.");

Quote marks must be used around messages and object names. This is important because some messages or object names may contain brackets or commas, which could confuse the compiler. This is also the case for the said command which will be described shortly.

if (has("Buckazoid(s)")) { .....   // no ambiguity here about where

                                   // the argument ends

If quote marks are part of the message or inventory object, a \ should be placed in front of these. To use a \, \\ should be used. \n can also be used for a new line.

The said test command uses different parameters to all the other commands. Where as the others use 8 bit arguments (0-255), said takes 16 bit arguments (0-65535). Also, the number of arguments in a said command can vary. The numbers given in the arguments are the word group numbers from the WORDS.TOK file.

if (said(4,80)) { .....

Words can also be given in place of the numbers:

if (said("look")) { .....

if (said("open","door")) { .....

Quote marks must also be used around the words.

Labels and the goto command

Labels are given like this:

Label1:

The label name can contain letters, numbers, and the characters "_" and ".". No spaces are allowed.

The goto command takes one parameter, the name of a label.

goto(Label1);

Comments

There are three ways that comments can be used.

// - rest of line is ignored

[ - rest of line is ignored

/* Text between these are ignored */

The /*...*/ can be nested:

/* comment start

  print("Hello");    // won't be run

  /*                 // a new comment start (will be ignored!)

    v32 = 15;        // won't be run

  */                 // uncomments the most inner comment

  print("Hey!");     // won't be run, still inside comments

*/                   // uncomments

Defines

To give vars, flags etc. proper names the #define command is used. The name of the define is given followed by the define value:

#define ego o0

#define room_descr "This is a large hall with tall pillars down each side."

Then the define name can be used in place of the define value:

draw(ego);

print(room_descr);

Define names can only be used in arguments of commands (including gotos and the v0 == 3 type syntax), although some compilers may allow you to use them anywhere.

Defines must be defined in the file before they are used.

The define name can contain letters, numbers, and the characters "_" and ".". No spaces are allowed.

Including files

You can include another file in your logic source code by using the #include command:

#include "file.txt"

When the compiler encounters the above line, it will replace it with the contents of file.txt.

It is a good idea to have all the defines that you need for multiple logics in an #include file, so if you need to change the define value you only have to do it once (although you will need to recompile all logics that use that define).

More on messages

In some cases you may want to assign a specific number to a message so you can refer to it in other places. This is done by using the #message command, followed by the number of the message then the message itself:

#message 4 "You can't do that now."

Then you can give the message number as the parameter in commands:

print(m4);

Or embed the message in commands as normal and the number you assigned to it before will be used:

print("You can't do that now.");

#message can be used anywhere in the file, so you do not have to set the message before you use it.

The return command

The return command is just a normal action command (number 0), with no arguments. This must be the last command in every logic.


Getting started

The best way to get started with the AGI logic language is by looking at the code of existing games. At the moment, there is no tutorial available, so this is the best way to get a feel for the language and how certain things are done. This help file is designed mainly as a reference, although it does contain a few general introductory topics. You should start by reading these, which will hopefully give you an idea about what the main features of the system are. Also, there is some useful information in the readme.txt for the template game.